Pan/tilt/zoom API

API Discovery

id=ptz-control

Property

Properties.API.HTTP.Version=3

Property

Properties.API.PTZ.Presets.Version=2.00 (The index for the preset that is the device's home position at start-up or when calling ptz.cgi?move=home)

Property

Properties.PTZ.PTZ=yes

Property

Properties.PTZ.DigitalPTZ=yes (Products with digital PTZ)

Property

Properties.Overview.Overview=yes (Products with Panopsis technology)

Property

Properties.Overview.MechanicalHybrid=yes (Products with Panopsis technology)

Property

Properties.PTZ.EmbeddedDrivers=yes(For when all previously uploadable ptz drivers are embedded in the camera firmware instead of externally published. This also means that it is not possible to upload any ptz drivers.)

Firmware

5.20 and later.

Various Pan tilt zoom parameters. All writable parameters may be directly modified.

This group contains a parameter for turning on/off PTZ functionality.

Toggling this parameter does not install/uninstall any driver.

For mechanical PTZ, the index # in PTZ.ImageSource.I# is the index of the video channel, starting on 0 for video channel 1. For digital PTZ, there is one group PTZ.ImageSource.I0, and the parameter PTZ.ImageSource.I0.PTZEnabled is used for enabling/disabling PTZ on all channels.

This group contains a parameter that informs about the current status of the drivers installed on the Axis product.

The dynamic parameter group PTZ.Support.S# is updated when a driver is installed on a video channel. A parameter in the group has the value true if the corresponding capability is supported by the driver. The index # is the video channel number which starts from 1.

An absolute operation means moving to a certain position, a relative operation means moving relative to the current position. Arguments referred to apply to PTZ control.

This dynamic group is updated when a driver is installed on a video channel. Index # is the video channel number, starting on 1. When it is possible to obtain the current position from the driver, for example the current pan position, it is possible to apply limit restrictions to the requested operation. For instance, if an absolute pan to position 150 is requested, but the upper limit is set to 140, the new pan position will be 140. This is the purpose of all but MinFieldAngle and MaxFieldAngle in this group. The purpose of those two parameters is to calibrate image centering.

The dynamic parameter group PTZ.Various.V# is updated when a driver is installed on a video channel. The index # is the video channel number which starts from 1.

The group consists of several different types of parameters for the video channel. To distinguish the parameter types, the group is presented as three different categories below.

The Enabled parameters determine if a specific feature can be controlled using ptz.cgi (see section PTZ control).

The default parameters set the default value for a specific function in the driver.

The various parameters have different types of functions.

This dynamic group is updated when a driver is installed on a video channel. Index # is the video channel number, starting on 1. The parameters in these groups are driver dependent and are hence not known in advance. They are described on the help pages that come with the driver installation.

This dynamic group is updated when a driver is installed on a video channel. Index # is the video channel number, starting on 1. The parameters in these groups are driver dependent and are hence not known in advance. Some of the parameters (described below) are supported by most drivers. For the rest of the parameters not described in this section please refer to the help pages that come with the driver installation.

The following parameter is supported by all products where PTZ.Support.SpeedCtl=true.

The following parameters are supported by most PTZ domes, however please note that some of the parameters are product specific.

The preset PTZ position configuration, that should be set using ptzconfig.cgi.

The # is replaced with a group number starting from zero, e.g. PTZ.Preset.P0.

This group contains the parameters that describes the individual preset positions.

This parameter group has been deprecated. Use the ptzconfig.cgi and ptz.cgi? query to manage the list of preset positions instead. As of version 2.00 of the PTZ preset API Properties.API.PTZ.Presets.Version=2.00 adding, updating and removing presets using param.cgi is no longer supported.

The response is sectioned for each camera/channel number, with each section containing a list of attribute/data pairs. The data can be either a single value or an entire array of entries each containing one or more key/value pairs. Please note that supported attributes are product dependent. Also, the order of cameras/channels sections in the response may not be in the number order.

Query attribute response format - plain text

Attributes for camera [n]
<attribute a>=<array entry1>, <array entry2>,...
<attribute b>=<array entry1>, <array entry2>,...
<attribute c>=<single value>
Attributes for camera [m]
...

The attribute array entries are comma separated while the key/value pairs are separated by a | as shown below:

<key 1>=<value 1>|<key 2>=<value 2>|...|<key N>=<value N>

Example

Attributes for camera 1
speeds=value=1|speed=0.05,value=9|speed=0.16,value=14|speed=2,value=24|speed=2.1,value=40|speed=9,value=58|speed=28,value=80|speed=74,value=100|speed=150
maxOpticalZoomMag=30

Query attribute response format - json

{
  "Camera <n>": {
    "<attribute a>": [<arrary entry 1>, <array entry 2>],
    "<attribute b>": [<arrary entry 1>, <array entry 2>],
    "<attribute c>": "<single value>"
  },
  "Camera <m>": {
    ...
  }
}

The attribute array entries are json objects with one or more key/value pairs:

{
  "<key 1>": "<value 1>",
  "<key 2>": "<value 2>",
  ...,
  "<key N>": "<value N>"
}

Example

{
  "Camera 1": {
    "maxOpticalZoomMag": "30",
    "zoomSteps": [
      {
        "value": "1",
        "zoom": "1"
      },
      {
        "value": "3868",
        "zoom": "2"
      },
      {
        "value": "7736",
        "zoom": "3"
      },
      {
        "value": "9999",
        "zoom": "3.584961"
      }
    ]
  }
}

A successful response for ptz.cgi.

HTTP code

204 No content

Content-type

text/plain

An error response for ptz.cgi.

HTTP code

200 OK

Content-type

text/plain

Error:
[message]

If PTZ is available a successful response for info=1. The generated response values for this argument depends on what functions the Axis product supports and what functions that are enabled.

HTTP code

200 OK

Content-type

text/plain

Available commands
:
{camera=[n]}
whoami=yes
center=[x],[y]
  imagewidth=[n]
  imageheight=[n]
areazoom=[x],[y],[z]
  imagewidth=[n]
  imageheight=[n]
move={ home | up | down | left | right | upleft | upright | downleft |
downright | stop }
pan=[abspos]
tilt=[abspos]
zoom=[n]
focus=[n]
iris=[n]
brightness=[offset]
rpan=[offset]
rtilt=[offset]
rzoom=[offset]
rfocus=[offset]
riris=[offset]
rbrightness=[offset]
autofocus={ on | off }
autoiris={ on | off }
ircutfilter={ on | off | auto }
backlight={ on | off }
continuouspantiltmove=[x-speed],[y-speed]
continuouszoommove=[speed]
continuousfocusmove=[speed]
continuousirismove=[speed]
continuousbrightnessmove=[speed]
auxiliary=[function]
setserverpresetname=[name]
setserverpresetno=[n]
removeserverpresetname=[name]
removeserverpresetno=[n]
gotoserverpresetname=[name]
gotoserverpresetno=[n]
gotodevicepreset=[n]
speed=[n]
osdmenu=[cmd]
query={ speed | position | limits | presetposcam | presetposall }

If PTZ is available a successful response for query=speed. The generated response values for this argument depends on what functions the Axis product supports and what functions that are enabled.

HTTP code

200 OK

Content-type

text/plain

speed=[speed]

If PTZ is available a successful response for query=position. The generated response values for this argument depends on what functions the Axis product supports and what functions that are enabled.

HTTP code

200 OK

Content-type

text/plain

pan=[abspos]
tilt=[abspos]
zoom=[n]
autofocus={ on | off }
autoiris={ on | off }

If PTZ is available a successful response for query=limits. The generated response values for this argument depends on what functions the Axis product supports and what functions that are enabled.

HTTP code

200 OK

Content-type

text/plain

MinPan=[abspos]
MaxPan=[abspos]
MinTilt=[abspos]
MaxTilt=[abspos]
MinZoom=[n]
MaxZoom=[n]
MinIris=[n]
MaxIris=[n]
MinFocus=[n]
MaxFocus=[n]
MinFieldAngle=[n]
MaxFieldAngle=[n]
MinBrightness=[offset]
MaxBrightness=[offset]

If PTZ is available a successful response for query=presetposcam.

HTTP code

200 OK

Content-type

text/plain

Preset Positions for camera [n]
presetposno[n]=p[n]
presetposno1=Home

If PTZ is available on a multichannel product several cameras can be listed. A successful response for query=presetposall .

HTTP code

200 OK

Content-type

text/plain

Preset Positions for camera 1
presetposno[n]=p[n]
presetposno1=Home
 
Preset Positions for camera 2
presetposno[n]=p[n]
presetposno1=Home
...

An error response for an invalid value, query=[invalid value].

HTTP code

200 OK

Content-type

text/plain

Error:
query: unknown value: [invalid value]

If PTZ is available a successful response for whoami=1.

HTTP code

200 OK

Content-type

text/plain

[Driver name]

A successful response for ptzconfig.cgi.

HTTP code

204 No content

Content-type

text/plain

An error response for ptzconfig.cgi.

HTTP code

200 OK

Content-type

text/plain

Error:
[message]

API version 1.0

API Discovery

id=ptz-driver-management version=1.0

Property

Properties.PTZ.DriverManagement=yes

Firmware

5.20 and later

Product category

Axis video products with serial ports.

API version 1.1

API Discovery

id=ptz-driver-management version=1.1

Property

Properties.PTZ.DriverManagement=yes

Property

Properties.PTZ.EmbeddedDrivers=yes

Firmware

10.12 and later

Product category

Axis video products with serial ports.

ptzupdate.cgi

Removed, since drivers are now associated with video channels and not directly with ports.

ptzadmin.cgi

Removed, ptzupgrader.cgi should be used instead.

ptzuploader.cgi to upload and remove PTZ drivers

Deprecated since API version 1.1. Support has been removed completely since API version 2.0.

The port argument used in ptzupgrader.cgi

Deprecated since API version 1.1. The port will always be set to the one required by the driver.

root.PTZ.PTZDrivers

Removed since API version 2.0. Use ptzuploader to list active drivers.

root.PTZ.PTZDriverVersions

Deprecated since API version 1.1, since the PTZ drivers are embedded in the software from that version. Removed completely since API version 2.0.

root.PTZ.SerDriverStatuses

Removed since API version 2.0 Use PTZ.PTZDriverStatuses instead.

This example will show you how to list all PTZ drivers available for activation and see which drivers are currently active. Available PTZ drivers have an ID that can be used to either activate or deactivate them.

1. List all PTZ drivers.

http://<servername>/axis-cgi/ptz/ptzuploader.cgi?list=yes

2. Parse the HTTP response. A response where a Pelco driver is active on channels 3 and 4 will look like this:

<?xml version="1.0"?>
  <driverentry>
    <id>1</id>
    <driver>Pelco</driver>
    <driverversion>4.17</driverversion>
    <installed>
      <ch>3</ch>
      <ch>4</ch>
    </installed>
    <deviceTypes>
      <deviceType>Generic</deviceType>
      <deviceType>DD5-C</deviceType>
      <deviceType>Esprit ES30C/ES31C</deviceType>
      <deviceType>LRD41C21</deviceType>
      <deviceType>LRD41C22</deviceType>
      <deviceType>Spectra III</deviceType>
      <deviceType>Spectra IV</deviceType>
      <deviceType>Spectra Mini</deviceType>
      <deviceType>Videotec DTRX3/PTH310P</deviceType>
      <deviceType>Videotec ULISSE</deviceType>
      <deviceType>PTK AMB</deviceType>
      <deviceType>YP3040</deviceType>
      <deviceType>XP40</deviceType>
    </deviceTypes>
    <deviceIdRange>
      <min>1</min>
      <max>255</max>
    </deviceIdRange>
  </driverentry>
  <driverentry>
    <id>2</id>
    <driver>Visca/EVI</driver>
    <driverversion>4.11</driverversion>
    <installed></installed>
    <deviceTypes>
      <deviceType>EVI-G20/G21</deviceType>
      <deviceType>EVI-D30/D31</deviceType>
      <deviceType>EVI-D100/D100P</deviceType>
      <deviceType>EVI-D70/D70P</deviceType>
      <deviceType>EVI-D70F/D70PF</deviceType>
      <deviceType>DCP-27</deviceType>
    </deviceTypes>
    <deviceIdRange>
      <min>1</min>
      <max>7</max>
    </deviceIdRange>
  </driverentry>
  <driverentry>
    <id>3</id>
    <driver>ARTP</driver>
    <driverversion>1.1.0</driverversion>
    <installed></installed>
  </driverentry>
  ...
</root>

3. List all PTZ drivers and the driver status for all channels.

http://<servername>/axis-cgi/ptz/ptzuploader.cgi?list=yes&status=yes

4. Parse the HTTP response. A response where a Pelco driver is active with the device type Generic and device id=1 on channel 1 will look like this:

<?xml version="1.0"?>
  <driverentry>
    <id>1</id>
    <driver>Pelco</driver>
    <driverversion>4.17</driverversion>
    <installed>
      <ch>1</ch>
    </installed>
    <deviceTypes>
      <deviceType>Generic</deviceType>
      <deviceType>DD5-C</deviceType>
      <deviceType>Esprit ES30C/ES31C</deviceType>
      <deviceType>LRD41C21</deviceType>
      <deviceType>LRD41C22</deviceType>
      <deviceType>Spectra III</deviceType>
      <deviceType>Spectra IV</deviceType>
      <deviceType>Spectra Mini</deviceType>
      <deviceType>Videotec DTRX3/PTH310P</deviceType>
      <deviceType>Videotec ULISSE</deviceType>
      <deviceType>PTK AMB</deviceType>
      <deviceType>YP3040</deviceType>
      <deviceType>XP40</deviceType>
    </deviceTypes>
    <deviceIdRange>
      <min>1</min>
      <max>255</max>
    </deviceIdRange>
  </driverentry>
  ...
  <status>
    <channel id="1">
      <activeDriver>
        <driverStatus>2</driverStatus>
        <driverId>1</driverId>
        <driverDeviceType>Generic</driverDeviceType>
        <driverDeviceId>1</driverDeviceId>
      </activeDriver>
    </channel>
    <channel id="2"></channel>
    <channel id="3"></channel>
    <channel id="4"></channel>
  <status>
</root>

HTTP/1.1 200 OK

HTTP/1.1 409

HTTP/1.1 400

This example will show you how to install a PTZ driver and perform PTZ movements on your camera. Individual addresses can be set for connected devices that are daisy chained.

1. Install a PTZ driver.

Install a PTZ driver with ID 2 on the default video channel.

http://<servername>/axis-cgi/ptz/ptzupgrader.cgi?driverid=2

Install a PTZ driver with ID 2 on video channel 1.

http://<servername>/axis-cgi/ptz/ptzupgrader.cgi?driverid=2&channel=1

Install a driver with ID 2 on video channel 1 using device type Generic and giving it the device ID address 1.

http://<servername>/axis-cgi/ptz/ptzupgrader.cgi?driverid=2&channel=1&deviceType=Generic&deviceId=1

2. Parse the HTTP response.

HTTP/1.1 200 OK

This error response will appear if the driver installation fails due to an invalid request.

HTTP/1.1 400

This error response will appear if the driver installation fails due to the product not being configured to use uploadable PTZ driver mode.

HTTP/1.1 409

This error response will appear if the driver installation fails due to misconfiguration or hardware errors.

HTTP/1.1 500

This error response will appear if the driver installation fails due to an already installed driver on the channel.

HTTP/1.1 501

This example will show you how to change the device type or device ID settings of an already active driver or video channel.

1. Change device ID settings to 2 for the driver with ID 1 that was previously activated on channel 1.

http://<servername>/axis-cgi/ptz/ptzupgrader.cgi?driverId=1&channel=1&deviceId=2

2. Change device type settings to “Spectra IV” for the Pelco driver with ID 1 previously active on channel 1.

http://<servername>/axis-cgi/ptz/ptzupgrader.cgi?driverId=1&channel=1&deviceType=Spectra%20IV

This example will show you how to uninstall a PTZ driver from a video channel.

1. Uninstall a PTZ driver from video channel 1.

http://<servername>/axis-cgi/ptz/ptzupgrader.cgi?driverid=0&channel=1

2. Parse the HTTP response.

HTTP/1.1 200 OK

This error response will appear if the driver uninstall fails due to misconfiguration or hardware errors.

HTTP/1.1 500

This error response will appear if the driver uninstall fails due to the product not being configured to use uploadable PTZ driver mode.

HTTP/1.1 409

This error response will appear if the driver uninstall fails due to the request being invalid.

HTTP/1.1 400

This example will show you how to check whether a PTZ driver is active on a channel.

The channel status is included in the response from any CGI request as long as the argument status=yes is provided. It is also possible to retrieve the status in a separate ptzuploader.cgi request. The status contains information related to active drivers on each channel, such as the driver status, ID and optionally also the device type and ID when this is supported.

1. Check if the driver is active on channel 1.

http://<servername>/axis-cgi/ptz/ptzuploader.cgi?status=yes

2. The following response will return for a 4–channel device if a Pelco driver with ID 1 is active on channel 1 with device type Generic and device id=1.

<?xml version="1.0"?>
<root>
  <status>
    <channel id="1">
      <activeDriver>
        <driverStatus>2</driverStatus>
        <driverId>1</driverId>
        <driverDeviceType>Generic</driverDeviceType>
        <driverDeviceId>1</driverDeviceId>
      </activeDriver>
    </channel>
    <channel id="2"></channel>
    <channel id="3"></channel>
    <channel id="4"></channel>
  <status>
</root>

HTTP/1.1 200 OK

This error response will appear if the GET status fails due to the product not being configured to use uploadable PTZ driver mode.

HTTP/1.1 409

This error response will appear if the GET status fails.

HTTP/1.1 400

This method should be used when you want to list available PTZ drivers.

Request

Access control

admin

Method

POST/GET

http://<servername>/axis-cgi/ptz/ptzuploader.cgi?<argument>=<value>[<argument>=<value>]

Return value - Success

Using list will return the driver listing in the following format:

<?xml version=1.0"?>
<root>
  <driverentry>
    <id>driverid</id>
    <driver>drivername</driver>
    <driverversion>driverversion</driverversion>
    <installed>
      <ch>1</ch>
      <ch>2</ch>
      ...
      <ch>n</ch>
    </installed>
    <deviceTypes>
      <deviceType>deviceType_1</deviceType>
      ...
      <deviceType>deviceType_N</deviceType>
    </deviceTypes>
    <deviceId>
      <min>min_device_id</min>
      <max>max_device_id</max>
    </deviceId>
  </driverentry>
  ...
</root>

Please note that there is one driverentry element for each available driver.

This method should be used when you want to install or uninstall a driver on a video channel. Drivers may have been previously uploaded, or may be included in the firmware of the product.

After activating a driver, the external device can be controlled using the Pan/tilt/zoom API and, if the driver supports it, Serial port API.

Request

Access control

admin

Method

GET/POST

http://<servername>/axis-cgi/ptz/ptzupgrader.cgi?<argument>=<value>[&<argument>=<value>...]

With the following arguments and values:

Response

<?xml version="1.0"?>
<root>
  <status>
    <channel id="1">
      <activeDriver>
        <driverStatus>driverstatus</driverStatus>
        <driverId>driverid</driverId>
        <driverDeviceType>devicetype</driverDeviceType>
        <driverDeviceId>deviceid<driverDeviceId>
      </activeDriver>
    </channel>
    ...
    <channel id="n"></channel>
  </status>
</root>

The Parameter management API should be used to implement the following parameters. Valid values for [video_channel] ranges from 1 to root.PTZ.NbrOfCameras.

root.PTZ.PTZDriverStatuses.Driver#Status

The parameters in this group are used when you want to find out the statuses for PTZ drivers associated with the (serial) ports.

List security level

viewer

PTZ.PTZDriverStatuses.Driver[video_channel]Status

An active driver with state 3 may briefly change to state 0 while it is reconfigured, such as when the device type is changed.

Property

Properties.API.HTTP.Version=3

Firmware

5.20 and later.

Products with mechanical PTZ require:

Property

Properties.PTZ.PTZ=yes

Products with digital PTZ require:

Property

Properties.PTZ.DigitalPTZ=yes

VAPIX® Focus recall is available if:

Property

Properties.MemoryZones.MemoryZones=yes

Additional read-only properties available through param.cgi:

Property

Properties.MemoryZones.MaxNbrOfMemoryZones=X

Property

Properties.MemoryZones.Version=0.1

API Discovery

id=ptz-focus-recall

Firmware: 6.25 and later.

Product category: PTZ or Zoom cameras.

VAPIX® Speed dry is available if:

Property

Properties.API.HTTP.Version=3

Property

Properties.SpeedDry.SpeedDry=yes

Firmware: 5.65 and later.

Product category: PTZ cameras.