How to integrate Hikvision PTZ function

1 Overview

This paper is intended to help integrators to integrate PTZ function. Common problems proposed
during integration are summarized here to help solve PTZ related ISAPI problems.

2. Integration flow

For IP Dome, no doubt PTZ function is generally supported; for IP Camera/IP Zoom, part of them
support PTZ, however, for IP Camera/IP Zoom don’t support PTZ but with RS485 serial port, PTZ
function also can be integrated. Therefore, I summarize out the following flow chart, which
shows the integration process clearly.

Device type

No IP camera/
IPDome?
IP zoom

No Support
Support PTZ
RS485

Yes Yes
Configure
Yes RS485 serial
port info and
decoder info
Pan Tilt Zoom
control

Preset/Patrol/
Homeposition/
Poweroffmemory

End

3 PTZ integration

(1)What’s the device type?

GET /ISAPI/System/deviceInfo
HTTP/1.1 200 OK
Date: Mon, 03 Nov 2014 17:44:10 GMT
Server: App-webs/
Connection: close
Content-Length: 968
Content-Type: application/xml

<?xml version="1.0" encoding="UTF-8"?>

<DeviceInfo version="2.0" xmlns="http://www.hikvision.com/ver20/XMLSchema">
<deviceName>IP DOME</deviceName>
<deviceID>92122690-8d22-11b5-845f-4419b71d9c6a</deviceID>
<deviceDescription>IPDome</deviceDescription>
<deviceLocation>hangzhou</deviceLocation>
<systemContact>Hikvision.China</systemContact>
<model>DS-2DF7284-AEL</model>
<serialNumber>DS-2DF7284-AEL20131119BBWR441624208B</serialNumber>
<macAddress>44:19:b7:1d:9c:6a</macAddress>
<firmwareVersion>V5.2.4</firmwareVersion>
<firmwareReleasedDate>build 141009</firmwareReleasedDate>
<encoderVersion>V6.2</encoderVersion>
<encoderReleasedDate>build 140922</encoderReleasedDate>
<bootVersion>V1.3.4</bootVersion>
<bootReleasedDate>100316</bootReleasedDate>
<hardwareVersion>0x0</hardwareVersion>
<deviceType>IPDome</deviceType>
<telecontrolID>88</telecontrolID>
<supportBeep>false</supportBeep>
<supportVideoLoss>true</supportVideoLoss>

</DeviceInfo>
You can see clearly the type via this item <deviceDescription>.
(2)How to judge whether one device support PTZ or not and the supported PTZ channel
number?
GET /ISAPI/PTZCtrl/channels
HTTP/1.1 200 OK
Date: Mon, 03 Nov 2014 16:45:16 GMT
Server: App-webs/
Connection: close
Content-Length: 754
Content-Type: application/xml

<?xml version="1.0" encoding="UTF-8"?>

<PTZChannelList version="2.0" xmlns="http://www.hikvision.com/ver20/XMLSchema">
<PTZChannel version="2.0" xmlns="http://www.hikvision.com/ver20/XMLSchema">
<id>1</id>
<enabled>true</enabled>
<videoInputID>1</videoInputID>
<panMaxSpeed>400</panMaxSpeed>
<tiltMaxSpeed>200</tiltMaxSpeed>
<presetSpeed>4</presetSpeed>
<autoPatrolSpeed>70</autoPatrolSpeed>
<keyBoardControlSpeed>normal</keyBoardControlSpeed>
<controlProtocol>PELCO-D</controlProtocol>
<controlAddress>
<enabled>true</enabled>
<Address>0</Address>
</controlAddress>
<defaultPresetID>1</defaultPresetID>
<panSupport>true</panSupport>
<tiltSupport>true</tiltSupport>
<zoomSupport>true</zoomSupport>
</PTZChannel>
</PTZChannelList >
If device supports PTZ, the response will have <PTZChannel> and at least one channel info will be
returned. Meanwhile you can see the channel number via <id>1</id>.
If devices don’t support PTZ, there is no <PTZChannel>, as follows:
<PTZChannelList version="2.0" xmlns="http://www.std-cgi.com/ver20/XMLSchema">
</PTZChannelList >
You also can see clearly pan/tilt/zoom are supported or not.
(3)How to judge one device with RS485 serial port or not?
GET /ISAPI/System/Serial/ports
HTTP/1.1 200 OK

Date: Mon, 03 Nov 2014 17:40:45 GMT

Server: App-webs/
Connection: close
Content-Length: 473
Content-Type: application/xml

<?xml version="1.0" encoding="UTF-8"?>

<SerialPortList version="2.0" xmlns="http://www.hikvision.com/ver20/XMLSchema">
<SerialPort version="2.0" xmlns="http://www.hikvision.com/ver20/XMLSchema">
<id>1</id>
<enabled>true</enabled>
<serialPortType>RS485</serialPortType>
<duplexMode>half</duplexMode>
<baudRate>9600</baudRate>
<dataBits>8</dataBits>
<parityType>none</parityType>
<stopBits>1</stopBits>
<flowCtrl>none</flowCtrl>
</SerialPort>

</SerialPortList>
(4) Configure RS485 serial port info and decoder info
The following parameters should be configured:
a. Baud rate
b. Data bits
c. Stop bits
d. Parity type: odd, even, none
e. Decoder address
1)Configure RS485 serial port info
Put /ISAPI/System/Serial/ports/1
Xml
PUT /ISAPI/System/Serial/ports/1 HTTP/1.1
Authorization: Basic YWRtaW46MTIzNDU=
Content-Type:text/xml
Content-Length:399

<SerialPort version="2.0" xmlns="http://www.isapi.org/ver20/XMLSchema">

<id>1</id>
<enabled>true</enabled>
<serialPortType>RS485</serialPortType>
<duplexMode>half</duplexMode>
<baudRate>2400</baudRate>
<dataBits>8</dataBits>
<parityType>none</parityType>
<stopBits>1</stopBits>
<flowCtrl>none</flowCtrl>
</SerialPort>
Response
HTTP/1.1 200 OK
Date: Tue, 04 Nov 2014 10:13:02 GMT
Server: App-webs/
Connection: close
Content-Length: 284
Content-Type: application/xml
<?xml version="1.0" encoding="UTF-8"?>
<ResponseStatus version="2.0" xmlns="http://www.hikvision.com/ver20/XMLSchema">
<requestURL>/ISAPI/System/Serial/ports/1</requestURL>
<statusCode>1</statusCode>
<statusString>OK</statusString>
<subStatusCode>ok</subStatusCode>
</ResponseStatus>

2)Configure decoder info

PUT /ISAPI/PTZCtrl/channels/1 to set the decoder type as’ PELCO-D’ and address as ‘1’.
PUT /ISAPI/PTZCtrl/channels/1 HTTP/1.1
Authorization: Basic YWRtaW46MTIzNDU=
Content-Type:text/xml
Content-Length:540

<PTZChannel version="2.0" xmlns="http://www.isapi.org/ver20/XMLSchema">

<id>1</id>
<enabled>true</enabled>
<videoInputID>1</videoInputID>
<panMaxSpeed>400</panMaxSpeed>
<tiltMaxSpeed>200</tiltMaxSpeed>
<presetSpeed>4</presetSpeed>
<autoPatrolSpeed>70</autoPatrolSpeed>
<keyBoardControlSpeed>normal</keyBoardControlSpeed>
<controlProtocol>PELCO-D</controlProtocol>
<controlAddress>
<enabled>false</enabled>
<Address>1</Address>
</controlAddress>
<defaultPresetID>1</defaultPresetID>
</PTZChannel>
(5) Pan Tilt Zoom control
PUT /ISAPI/PTZCtrl/channels/1/continuous
xml
<PTZData version="2.0" xmlns="http://www.isapi.org/ver20/XMLSchema">
<pan> xx </pan>
<tilt> yy </tilt>
<zoom> zz </zoom>
</PTZData>
When xx>0, pan move right, when xx<0,pan move left; when yy>0, tilt move up, when yy<0, tilt
move down; when zz>0,zoom in, when zz<0,zoom out. The value range is -100~100, and 0
represents stop.
You can control the three items separately or together.
(6) Preset set and call
1)Set a preset
PUT /ISAPI/PTZCtrl/channels/1/presets/1
xml
<PTZPreset version="2.0" xmlns="http://www.isapi.org/ver20/XMLSchema">
<enabled>true</enabled>
<id>1</id>
<presetName> NetSpeedDome_preset 1</presetName>
</PTZPreset>
Response
HTTP/1.1 200 OK
Date: Wed, 05 Nov 2014 10:55:08 GMT
Server: App-webs/
Connection: close
Content-Length: 291
Content-Type: application/xml
<?xml version="1.0" encoding="UTF-8"?>
<ResponseStatus version="2.0" xmlns="http://www.hikvision.com/ver20/XMLSchema">
<requestURL>/ISAPI/PTZCtrl/channels/1/presets/1</requestURL>
<statusCode>1</statusCode>
<statusString>OK</statusString>
<subStatusCode>ok</subStatusCode>
</ResponseStatus>
2)Call a preset
PUT /ISAPI/PTZCtrl/channels/1/presets/1/goto
Response
HTTP/1.1 200 OK
Date: Wed, 05 Nov 2014 10:53:40 GMT
Server: App-webs/
Connection: close
Content-Length: 296
Content-Type: application/xml
<?xml version="1.0" encoding="UTF-8"?>
<ResponseStatus version="2.0" xmlns="http://www.hikvision.com/ver20/XMLSchema">
<requestURL>/ISAPI/PTZCtrl/channels/1/presets/1/goto</requestURL>
<statusCode>1</statusCode>
<statusString>OK</statusString>
<subStatusCode>ok</subStatusCode>
</ResponseStatus>
(7) Get the preset list of one channel
GET /ISAPI/PTZCtrl/channels/1/presets
Response
HTTP/1.1 200 OK
Date: Wed, 05 Nov 2014 10:58:19 GMT
Server: App-webs/
Connection: close
Content-Length: 3213
Content-Type: application/xml
<?xml version="1.0" encoding="UTF-8"?>
<PTZPresetList version="2.0" xmlns="http://www.hikvision.com/ver20/XMLSchema">
<PTZPreset>
<enabled>true</enabled>
<id>1</id>
<presetName> NetSpeedDome_preset 1</presetName>
</PTZPreset>
<PTZPreset>
<enabled>true</enabled>
<id>2</id>
<presetName>Preset 2</presetName>
</PTZPreset>
<PTZPreset>
<enabled>true</enabled>
<id>33</id>
<presetName>Auto-flip</presetName>
</PTZPreset>
<PTZPreset>
<enabled>true</enabled>
<id>34</id>
<presetName>Back to origin</presetName>
</PTZPreset>
<PTZPreset>
<enabled>true</enabled>
……
<id>105</id>
<presetName>Call patrol 8</presetName>
</PTZPreset>

</PTZPresetList>
In this <PTZPresetList>, all presets that have been set will be listed here. There are 105 presets
have been set for this example.
(8) Patrol set and call
1)Set patrol
PUT /ISAPI/PTZCtrl/channels/1/patrols/1
xml
<PTZPatrol version="2.0" xmlns="http://www.isapi.org/ver20/XMLSchema">
<enabled>true</enabled>
<id>1</id>
<patrolName>1</patrolName>
<PatrolSequenceList>
<PatrolSequence>
<id>1</id>
<presetID>1</presetID>
<seqSpeed>30</seqSpeed>
<delay>2</delay>
</PatrolSequence>
<PatrolSequence>
<id>2</id>
<presetID>2</presetID>
<seqSpeed>30</seqSpeed>
<delay>2</delay>
</PatrolSequence>
</PatrolSequenceList>
</PTZPatrol>
<patrolName> represents one patrol, each preset begin with <PatrolSequence>.

Response
HTTP/1.1 200 OK
Date: Wed, 05 Nov 2014 11:35:46 GMT
Server: App-webs/
Connection: close
Content-Length: 291
Content-Type: application/xml
<?xml version="1.0" encoding="UTF-8"?>
<ResponseStatus version="2.0" xmlns="http://www.hikvision.com/ver20/XMLSchema">
<requestURL>/ISAPI/PTZCtrl/channels/1/patrols/1</requestURL>
<statusCode>1</statusCode>
<statusString>OK</statusString>
<subStatusCode>ok</subStatusCode>
</ResponseStatus>
2)Call patrol
PUT /ISAPI/PTZCtrl/channels/1/patrols/1/start
Response
HTTP/1.1 200 OK
Date: Wed, 05 Nov 2014 14:44:05 GMT
Server: App-webs/
Connection: close
Content-Length: 297
Content-Type: application/xml
<?xml version="1.0" encoding="UTF-8"?>
<ResponseStatus version="2.0" xmlns="http://www.hikvision.com/ver20/XMLSchema">
<requestURL>/ISAPI/PTZCtrl/channels/1/patrols/1/start</requestURL>
<statusCode>1</statusCode>
<statusString>OK</statusString>
<subStatusCode>ok</subStatusCode>
</ResponseStatus>
Send PUT /ISAPI/PTZCtrl/channels/1/patrols/1/stop to stop the patrol.
(9)How to configure the homeposition?
PUT /ISAPI/PTZCtrl/channels/1/homeposition
Response
HTTP/1.1 200 OK
Date: Wed, 05 Nov 2014 15:14:21 GMT
Server: App-webs/
Connection: close
Content-Length: 294
Content-Type: application/xml
<?xml version="1.0" encoding="UTF-8"?>
<ResponseStatus version="2.0" xmlns="http://www.hikvision.com/ver20/XMLSchema">
<requestURL>/ISAPI/PTZCtrl/channels/1/homeposition</requestURL>
<statusCode>1</statusCode>
<statusString>OK</statusString>
<subStatusCode>ok</subStatusCode>
</ResponseStatus>
The current PT position will be set as homeposition.
Note: zoom position isn’t included in homeposition.
Send PUT /ISAPI/PTZCtrl/channels/1/homeposition/goto to call the homeposition.
(10)How to configure Power off memory?
Power off memory function is used to memorize the PTZ position before power off.
1)Get the power off memory info
GET /ISAPI/PTZCtrl/channels/1/saveptzpoweroff
Response
HTTP/1.1 200 OK
Date: Wed, 05 Nov 2014 15:43:25 GMT
Server: App-webs/
Connection: close
Content-Length: 192
Content-Type: application/xml
<?xml version="1.0" encoding="UTF-8"?>
<savePtzPoweroff version="2.0" xmlns="http://www.hikvision.com/ver20/XMLSchema">
<savePtzPoweroffType>30sec</savePtzPoweroffType>

</savePtzPoweroff>
2)Set the power off memory
PUT /ISAPI/PTZCtrl/channels/1/saveptzpoweroff
XML
<savePtzPoweroff version="2.0" xmlns="http://www.isapi.org/ver20/XMLSchema">
<savePtzPoweroffType>30sec</savePtzPoweroffType>
</savePtzPoweroff>
Note: <savePtzPoweroffType> parameter options can be 30sec, 60sec, 300sec, 600sec and
disable. When the option is ‘disable’, it means, power off memory is closed.
Response
HTTP/1.1 200 OK
Date: Wed, 05 Nov 2014 15:51:53 GMT
Server: App-webs/
Connection: close
Content-Length: 297
Content-Type: application/xml
<?xml version="1.0" encoding="UTF-8"?>
<ResponseStatus version="2.0" xmlns="http://www.hikvision.com/ver20/XMLSchema">
<requestURL>/ISAPI/PTZCtrl/channels/1/saveptzpoweroff</requestURL>
<statusCode>1</statusCode>
<statusString>OK</statusString>
<subStatusCode>ok</subStatusCode>
</ResponseStatus>