HIKCGI PTZ Function Description

This documentation describes how to integrate PTZ function with HIKCGI protocol,
and the main content is to configure and control mechanical PTZ by HIKCGI protocol.
Before reading this documentation, please read HIKCGI Integration Guide at first.

1 Overview

1.1 PTZ Function Description

PTZ is such equipment that is used to control movement of the device. For a device
supporting PTZ, you can send CGI commands to control its movement, including Pan,
Tile, Zoom, preset, patrol and so on.
But firstly, we need to clarity a concept: some devices have their own PTZ, for
example, Speed Dome; other devices dont have their own PTZ, but these devices can
connect with external PTZ decoder so as to support PTZ function, for example, network
camera.
The above-mentioned difference will produce different operations. For network
camera without PTZ, you need to connect network camera with external PTZ decoder
via RS-485 serial port, therefore, the first step is to configure corresponding parameters
of 485 serial port correctly, then send PTZ commands to external PTZ decoder to control
the movement of the device. If the device has its own PTZ, you dont need to configure
these parameters. Please note that for IPC, DVS, /PTZ// commands are used. For
Type C of IPC, after V4.0.3, it also supports /PTZCtrl// commands.

Note: You should configure the 485 serial ports before operating the PTZ, the parameters of the RS485 should match with the configuration of the external PTZ decoder, otherwise the command sent to
the PTZ will not be decoded correctly.

1.2 Ensuring the command path of the device

There are two branches of PTZ Commands in HIKCGI Protocol. One is /PTZ
(Section 8.12 for reference); the other is /PTZCtrl (Section 8.13 for reference). Currently,
IPC (before V4.0.3), DVS and DVR only support /PTZ and Speed Dome supports
/PTZCtrl.
To check which branch the device supports, you can send GET /index request; this
command will list all of the service branches. If /PTZ service branch is listed, then it is
the protocol branch mentioned in Section 8.12. If /PTZCtrl command is listed, it goes to
the protocol branch mentioned in Section 8.13.
Example:
<?xml version="1.0" encoding="UTF-8"?>
<ResourceList version="1.0" xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns="http://www.hikvision.com/ver10/XMLSchema">
<Resource version="1.0" xlink:href="/index">

<name>index</name>
<type>Special Resource</type>
</Resource>
<Resource version="1.0" xlink:href="/indexr">
<name>index</name>
<type>Special Resource</type>
</Resource>
<Resource version="1.0" xlink:href="/description">
<name>description</name>
<type>Special Resource</type>
</Resource>
<Resource version="1.0" xlink:href="/System">
<name>System</name>
<type>Service</type>
</Resource>
... ...
<Resource version="1.0" xlink:href="/PTZ">
<name>PTZ</name>
<type>Service</type>
</Resource>
</ResourceList>
From the above example, the path of returned command is /PTZ, you should use the
definition mentioned in HIKCGI 1.5.9 to control PTZ function of the device.

2 PTZ Function Development

The section will describe the detailed steps of PTZ function development.

2.1 Checking whether a device supports PTZ

You can send GET /PTZCtrl/channels request to get the number of PTZ channels of
the device. If the device supports PTZ function, a piece of channel information at least
will be returned; otherwise, an empty list will be returned.
Example:
GET /PTZCtrl/channels HTTP/1.1
Host: 172.8.11.101
Authorization: Basic YWRtaW46MTIzNDU=

The response is as follows:

HTTP/1.1 200 OK
Server: App-webs/
Connection: close
Content-Length: 259
Content-Type: application/xml
<?xml version="1.0" encoding="UTF-8"?>
<PTZChannelList>
<PTZChannel>
<id>1</id>
<enabled>true</enabled>
<videoInputID>1</videoInputID>
</PTZChannel>
</PTZChannelList>
<PTZChannelList> is a list. All of PTZ channels will be listed in this list. From the
above example, <PTZChannelList> has one <PTZChannel>, indicating that the device
supports PTZ function.
You can send GET/Serial/ports/1/index request to check whether the device has
RS-485 serial port, if response is HTTP OK, it indicated that the device supports RS-485
serial port, otherwise if response is 400 Bad Request, it indicated that the device doesnt
support RS-485 serial port, you cant install external PTZ decoder, either. (Section 2.2.5
of HIKCGI Integration Guide for reference)

2.2 Configuring RS-485 serial port and parameters of External

Decoder
For some devices with external PTZ decoder, in general, we connect these devices
with external PTZ decoder via 485 serial ports, so the first step is to configure
corresponding parameters of 485 serial ports and ensure that these parameters match with
the parameters of the external PTZ decoder.
Please configure the following parameters:

Baud Rate

Data Bits

Stop Bits

Parity Type

Decoder Type

Decoder Address

Example: for a mechanical PTZ supporting PELCO protocol, configuration

parameters of the PTZ are as follows:
1. Baud Rate: 2400bps
2. Data Bits: 8bps
3. Stop Bits: 1bps
4. Parity Type: None
5. Decoder type: PELCO_D
6. Decoder Address: 1
1.

Configuring parameters of RS 485 serial port

You can send PUT/Serial/Ports/1 command to configure these parameters, as

follows:
PUT /Serial/ports/1 HTTP/1.1
Authorization: Basic YWRtaW46MTIzNDU=
Host:172.8.6.176
Content-Type:text/xml
Content-Length:313
<?xml version="1.0" encoding="UTF-8"?>
<SerialPort version="1.0" xmlns="http://www.hikvision.com/ver10/XMLSchema">
<id>1</id>
<enabled>true</enabled>
<serialPortType>RS485</serialPortType>
<baudRate>2400</baudRate>
<dataBits>8</dataBits>
<parityType>none</parityType>
<stopBits>1</stopBits>
</SerialPort>
Baud Rate, Data Bits, Stop Bits and Parity Type can be configured by
PUT/Serial/Ports/1 command, but Decoder Type and Decoder Address need to be
configured by PUT/PTZ/Channels/1.
2. Configuring the parameters of the decoder

The parameters of decoder include Decoder Type and Decoder Address; it can be
configured by PUT /PTZ/channels/1.
Based on above-mentioned example in Section 2.2, we set Decoder Type as
PELCO_D and Decoder Address as 1, as follows:
PUT /PTZ/channels/1 HTTP/1.1
Authorization: Basic YWRtaW46MTIzNDU=
Host:172.8.6.176
Content-Type:text/xml
Content-Length:254
<?xml version="1.0" encoding="UTF-8"?>
<PTZChannel version="1.0"
xmlns="http://www.hikvision.com/ver10/XMLSchema">
<id>1</id>
<videoInputID>1</videoInputID>
<controlProtocol>PELCO_D</controlProtocol>
<controlAddress>1</controlAddress>
</PTZChannel>

2.3 Common PTZ Commands

2.3.1 PTZ control (Pan/Tilt/Zoom)
PTZ control includes Pan, Tile and Zoom. A command can designate Pan and Tile
simultaneously. The device will rotate as specific angle. The format of PTZ command is
as follows:
<PTZData>
<pan>xx</pan>
<tilt>yy</tilt>
<zoom>zz</zoom>
</PTZData>
<pan>: horizontal speed. When the value is greater than 0, the device will move
towards the right; when the value is smaller than 0, the device will move towards the left;
when the value equals 0, horizontal movement is stopped.
<tilt>: vertical speed. When the value is greater than 0, it moves upwards; when the
value is smaller than 0, it moves downwards; when the value equals 0, vertical movement
is stopped.
The diagram of <pan> and <tilt> is as follows:

<zoom> is speed of optical zoom. When the value is greater than 0, it zooms in;
when the value is smaller than 0, it zooms out.
<pan>,<tile> and <zoom> can be used together, you can also use one of them. In
general, you can use <pan> and <tile> simultaneously to control the movement of PTZ
as specific angle; The speed of <zoom> ranges from -100 to 100. 0: stop movement.
Example: The device moves towards the left and the speed is 60.
PUT /PTZCtrl/channels/1/continuous HTTP/1.1
Host: 172.8.11.101
Content-Type: text/xml
Authorization: Basic YWRtaW46MTIzNDU=
Content-Length: 95
<?xml version="1.0" encoding="UTF-8"?>
<PTZData>
<pan>-60</pan>
<tilt>0</tilt>
</PTZData>
Example: Stop horizontal movement.
PUT /PTZCtrl/channels/1/continuous HTTP/1.1
Host: 172.8.11.101

Content-Type: text/xml
Authorization: Basic YWRtaW46MTIzNDU=
Content-Length: 93
<?xml version="1.0" encoding="UTF-8"?>
<PTZData>
<pan>0</pan>
<tilt>0</tilt>
</PTZData>
Example: The device moves upwards, and the speed is 60.
PUT /PTZCtrl/channels/1/continuous HTTP/1.1
Authorization: Basic YWRtaW46MTIzNDU=
Content-Type: text/xml
Host: 172.8.11.101
Content-Length: 94
<?xml version="1.0" encoding="UTF-8"?>
<PTZData>
<pan>0</pan>
<tilt>60</tilt>
</PTZData>
Example: The device moves toward the upper right and the speed is 60.
PUT /PTZCtrl/channels/1/continuous HTTP/1.1
Authorization: Basic YWRtaW46MTIzNDU=
Content-Type: text/xml
Host: 172.8.11.101
Content-Length: 95
<?xml version="1.0" encoding="UTF-8"?>
<PTZData>
<pan>60</pan>
<tilt>60</tilt>

</PTZData>
Example: Set the camera to zoom in.
PUT /PTZCtrl/channels/1/continuous HTTP/1.1
Authorization: Basic YWRtaW46MTIzNDU=
Content-Type: text/xml
Host: 172.8.11.101
Content-Length: 80
<?xml version="1.0" encoding="UTF-8"?>
<PTZData>
<zoom>60</zoom>
</PTZData>

2.3.2 Setting and calling Preset

When PTZ moves a certain position, you can send PUT /PTZCtrl/channels/1/presets/ID
command to record current position. When you want to call the preset next time, the
camera will move to the same position.
1. Setting a preset
PUT /PTZCtrl/channels/1/presets/ID command is used to record current position as a
preset, you can designate the name of the preset in order to identify it easily.
Example:
PUT /PTZCtrl/channels/1/presets/1 HTTP/1.1
Authorization: Basic YWRtaW46MTIzNDU=
Content-Type: text/xml
Host: 172.8.11.101
Content-Length: 139
<?xml version="1.0" encoding="UTF-8"?>
<PTZPreset>
<id>1</id>
<enabled>true</enabled>

<presetName>Preset-1</presetName>
</PTZPreset>
2. Calling Preset
PUT /PTZCtrl/channels/1/presets/ID/goto command is used to call an existing preset.
ID is the identifier of a preset. This command does not need HTTP body; ID is the
only parameter, so HTTP Header doesnt include Content-Length and Content-Type.
Example:
PUT /PTZCtrl/channels/1/presets/1/goto HTTP/1.1
Authorization: Basic YWRtaW46MTIzNDU=
Host: 172.8.11.101

3. Getting the list of presets

GET /PTZCtrl/channels/1/presets request is used to get all of the presets of current PTZ
channel.
Example:
GET /PTZCtrl/channels/1/presets HTTP/1.1
Host: 172.8.11.101
Authorization: Basic YWRtaW46MTIzNDU=

The response is as follows:

HTTP/1.1 200 OK
Connection: close
Content-Length: 8651
Content-Type: application/xml
<?xml version="1.0" encoding="UTF-8"?>
<PTZPresetList>
<PTZPreset>
<id>1</id>

<enabled>true</enabled>
<presetName>1</presetName>
</PTZPreset>
<PTZPreset>
<id>2</id>
<enabled>true</enabled>
<presetName>2</presetName>
</PTZPreset>

<PTZPreset>
<id>128</id>
<enabled>true</enabled>
<presetName>128</presetName>
</PTZPreset>
</PTZPresetList>
<PTZPresetList> is a list of all of the presets of current PTZ channel. Each
<PTZPreset> stands for a preset. From the above example, there are 128 presets in
current PTZ channel.

2.3.3 Setting and Calling Patrol

A patrol can consist of many presets. When a patrol is called, the device will rotate as
the sequence of presets called in the patrol. You can set the delay time and the speed of
each preset.
1. Setting a Patrol
PUT /PTZCtrl/channels/1/patrols/ID command is used to set a patrol. ID is the
identifier of a patrol. All of the presets that need to be set will be listed in the command.
Example:
PUT /PTZCtrl/channels/1/patrols/1 HTTP/1.1
Authorization: Basic YWRtaW46MTIzNDU=
Content-Type:text/xml

Content-Length:466
<PTZPatrol version="1.0" xmlns="http://www.hikvision.com/ver10/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>
<PatrolSequenceList> is a list. All of the presets of the patrol will be listed in this list.
The information of each preset is included in a <PatrolSequence>.
<id> refers to the sequence of presets of a patrol in the <PatrolSequence>; <presetID>
stands for the identifier of a preset; <delay> means the delay time (unit is milliseconds);
<seqSpeed> stands for the speed of the movement, the value of <seqSpeed> ranges from
1 to 100.
2. Calling a patrol
PUT /PTZCtrl/channels/1/patrols/ID/start is used to start a patrol. ID is the
identifier of a patrol. This command does not need HTTP body; ID is the only
parameter, so HTTP Header doesnt include Content-Length and Content-Type.

Example:
PUT /PTZCtrl/channels/1/patrols/1/start HTTP/1.1
Host:172.8.11.101
Authorization: Basic YWRtaW46MTIzNDU=
3. Stopping a patrol
PUT /PTZCtrl/channels/1/patrols/ID/stop is used to stop a patrol. ID is the
identifier of a patrol. This command does not need HTTP body; ID is the only
parameter, so HTTP Header doesnt include Content-Length and Content-Type.
Example:
PUT /PTZCtrl/channels/1/patrols/1/stop HTTP/1.1
Host:172.8.11.101
Authorization: Basic YWRtaW46MTIzNDU=

2.4 Special PTZ commands

2.4.1 Home Position
Home position is zero coordinate of horizontal and vertical coordinates. The value is
(0, 0). You can use PUT/PTZCtrl/channels/<ID>/homeposition command to set any
current position as home position. Follow-up PTZ control will be based on this
coordinate system.
Example:
PUT /PTZCtrl/channels/1/homeposition HTTP/1.1
Host:172.8.11.101
Authorization: Basic YWRtaW46MTIzNDU=
Note: The command doesnt need HTTP Body. The device only will record current position as
Home position when you send this command.

PUT/PTZCtrl/channels/<ID>/homeposition/goto is used to call home position. The

device will move to home position when the command is called.

Example:
PUT /PTZCtrl/channels/1/homeposition/goto HTTP/1.1
Host:172.8.11.101
Authorization: Basic YWRtaW46MTIzNDU=

2.4.2 Power off Memory

The function is used to record the power off position capability with the predefined dwell
time. It allows the dome to resume its previous position after power is restored.
Example: Get Power off memory information
GET /PTZCtrl/channels/1/saveptzpoweroff HTTP/1.1
Host:172.8.11.101
Authorization: Basic YWRtaW46MTIzNDU=

The response is as follows:

HTTP/1.1 200 OK
Connection: close
Content-Length: 192
Content-Type: application/xml
<?xml version="1.0" encoding="UTF-8"?>
<savePtzPoweroff version="1.0"
xmlns="http://www.hikvision.com/ver10/XMLSchema">
<savePtzPoweroffType>30sec</savePtzPoweroffType>
</savePtzPoweroff>
<savePtzPoweroffType> supports the following options: disable, 30sec, 60sec,
300sec, 600sec.
Example: Set Power Off Memory function:
PUT /PTZCtrl/channels/1/saveptzpoweroff HTTP/1.1

Authorization: Basic YWRtaW46MTIzNDU=

Content-Type:text/xml
Content-Length:156
<savePtzPoweroff version="1.0"
xmlns="http://www.hikvision.com/ver10/XMLSchema">
<savePtzPoweroffType>disable</savePtzPoweroffType>
</savePtzPoweroff>
The above example sets Power off Memory disabled.

2.5 PTZ commands for Type C of IPC (before V4.0.3), DVS and
DVR
2.5.1 PTZ Commands Description
The general PTZ command format is:
PUT /PTZ/channels/1/PTZControl?command=XXX&mode=YY&speed=N
command, mode and speed are three primary parameters.
The common options of command are as follows:

PAN_LEFT :

PAN_RIGHT:

TILT_UP:

TILT_DOWN:

ZOOM_IN:

ZOOM_OUT:

UP_LEFT:

UP_RIGHT:

DOWN_LEFT:

DOWN_RIGHT:

PAN_AUTO:

mode includes two options: start and stop

speed stands for the speed that PTZ rotates. The value ranges from 1 to 7, the greater the

value is, and the faster the speed is.

2.5.2 Usage of PTZ commands

Example: The device rotates towards the left and the speed is 3 or 4.
PUT /PTZ/channels/1/PTZControl?command=PAN_LEFT&mode=start&speed=3
HTTP/1.1
Authorization: Basic YWRtaW46MTIzNDU=
Host:172.8.6.176
If this command takes effect, the device will return OK firstly and then start moving.
The response is as follows:
HTTP/1.1 200 OK
Date: Mon, 16 Jul 2012 20:17:13 GMT
Server: App-webs/
Connection: close
Content-Length: 246
Content-Type: application/xml
<?xml version="1.0" encoding="UTF-8"?>
<ResponseStatus version="1.0" xmlns="http://www.stdcgi.com/ver10/XMLSchema">
<requestURL>/PTZ/channels/1/PTZControl</requestURL>
<statusCode>1</statusCode>
<statusString>OK</statusString>
</ResponseStatus>
Please note that if you want to stop the movement, please use the stop command,
otherwise, the device will keep moving.
Example:
PUT /PTZ/channels/1/PTZControl?command=PAN_LEFT&mode=stop&speed=3
HTTP/1.1
Authorization: Basic YWRtaW46MTIzNDU=
Host:172.8.6.176

If this command takes effect, the camera will return OK firstly and then stop moving.
The response is as follows:
HTTP/1.1 200 OK
Date: Mon, 16 Jul 2012 20:17:13 GMT
Server: App-webs/
Connection: close
Content-Length: 246
Content-Type: application/xml
<?xml version="1.0" encoding="UTF-8"?>
<ResponseStatus version="1.0" xmlns="http://www.stdcgi.com/ver10/XMLSchema">
<requestURL>/PTZ/channels/1/PTZControl</requestURL>
<statusCode>1</statusCode>
<statusString>OK</statusString>
</ResponseStatus>