Guard tour API

A preset tour is a guard tour which is set up using PTZ preset positions. The tour displays the preset positions one-by-one in a predefined order or at random and for configurable time periods.

Preset tours are defined by parameters in the dynamic GuardTour.G# group. Dynamic parameters are configured using param.cgi, see VAPIX® Parameter Management.

To set up a guard tour using preset positions:

To set up a guard tour using preset positions:

1. Create the preset positions using /com/ptzconfig.cgi, see section PTZ configuration.

2. Create the group GuardTour.G#.

3. Add preset positions to the guard tour group. Each position is added as a dynamic subgroup GuardTour.G#.Tour.T#.

4. Start the guard tour or schedule the guard tour using action rules (firmware 5.50 and later) or scheduled event types (firmware 5.00 to 5.4x).

If adding a nonexisting preset position, the subgroup will still be created but the preset will be ignored when running the tour. Similarly, if a preset position is removed, the tour is still valid and the missing preset is ignored.

Identification

Create a preset tour

The examples in this section demonstrate how to set up a guard tour using preset positions. The tour is defined by parameters in the dynamic GuardTour group.

http://myserver/axis-cgi/param.cgi?action=list&group=Properties.GuardTour

HTTP/1.0 200 OK
Content-Type: text/plain
 
root.Properties.GuardTour.GuardTour=yes

http://myserver/axis-cgi/param.cgi?action=add&group=GuardTour&template=guardtour

HTTP/1.0 200 OK
Content-Type: text/plain
 
G0 OK

http://myserver/axis-cgi/param.cgi?action=list&group=GuardTour.G0

HTTP/1.0 200 OK
Content-Type: text/plain
 
root.GuardTour.G0.Running=no
root.GuardTour.G0.Name=GuardtourName
root.GuardTour.G0.CamNbr=1
root.GuardTour.G0.RandomEnabled=no
root.GuardTour.G0.TimeBetweenSequences=0

http://myserver/axis-cgi/param.cgi?action=update&GuardTour.G0.Name=DayTour

HTTP/1.0 200 OK
Content-Type: text/plain
 
OK

http://myserver/axis-cgi/param.cgi?action=add&group=GuardTour&template=guardtour
&GuardTour.G.Name=NightTour

HTTP/1.0 200 OK
Content-Type: text/plain
 
G1 OK

Add preset positions to the tour

The examples in this section demonstrate how to add preset positions to the guard tour GuardTour.G0. Each preset positions is a dynamic subgroup GuardTour.G0.Tour.T#.

http://myserver/axis-cgi/com/ptz.cgi?query=presetposall

HTTP/1.0 200 OK
Content-Type: text/plain
 
Preset Positions for camera 1
presetposno5=North
presetposno4=West
presetposno3=South
presetposno2=East
presetposno1=Home

http://myserver/axis-cgi/param.cgi?action=add&group=GuardTour.G0.Tour&template=tour
&GuardTour.G0.Tour.T.PresetNbr=1
&GuardTour.G0.Tour.T.Position=1

HTTP/1.0 200 OK
Content-Type: text/plain
 
T0 OK

http://myserver/axis-cgi/param.cgi?action=list&group=GuardTour.G0.Tour.T0

HTTP/1.0 200 OK
Content-Type: text/plain
 
root.GuardTour.G0.Tour.T0.PresetNbr=1
root.GuardTour.G0.Tour.T0.Position=1
root.GuardTour.G0.Tour.T0.MoveSpeed=70
root.GuardTour.G0.Tour.T0.WaitTime=10
root.GuardTour.G0.Tour.T0.WaitTimeViewType=Seconds

http://myserver/axis-cgi/param.cgi?action=add&group=GuardTour.G0.Tour&template=tour
&GuardTour.G0.Tour.T.PresetNbr=2
&GuardTour.G0.Tour.T.Position=2

HTTP/1.0 200 OK
Content-Type: text/plain
 
T1 OK

http://myserver/axis-cgi/param.cgi?action=list&group=GuardTour.G0.Tour.T1

HTTP/1.0 200 OK
Content-Type: text/plain
 
root.GuardTour.G0.Tour.T1.PresetNbr=2
root.GuardTour.G0.Tour.T1.Position=2
root.GuardTour.G0.Tour.T1.MoveSpeed=70
root.GuardTour.G0.Tour.T1.WaitTime=10
root.GuardTour.G0.Tour.T1.WaitTimeViewType=Seconds

http://myserver/axis-cgi/param.cgi?action=add&group=GuardTour.G0.Tour&template=tour
&GuardTour.G0.Tour.T.PresetNbr=5
&GuardTour.G0.Tour.T.Position=3

HTTP/1.0 200 OK
Content-Type: text/plain
 
T2 OK

http://myserver/axis-cgi/param.cgi?action=list&group=GuardTour.G0.Tour.T2

HTTP/1.0 200 OK
Content-Type: text/plain
 
root.GuardTour.G0.Tour.T2.PresetNbr=5
root.GuardTour.G0.Tour.T2.Position=3
root.GuardTour.G0.Tour.T2.MoveSpeed=70
root.GuardTour.G0.Tour.T2.WaitTime=10
root.GuardTour.G0.Tour.T2.WaitTimeViewType=Seconds

http://myserver/axis-cgi/param.cgi?action=list&group=GuardTour.G0.Tour.*.PresetNbr

HTTP/1.0 200 OK
Content-Type: text/plain
 
root.GuardTour.G0.Tour.T0.PresetNbr=1
root.GuardTour.G0.Tour.T1.PresetNbr=2
root.GuardTour.G0.Tour.T2.PresetNbr=5

http://myserver/axis-cgi/param.cgi?action=remove&group=GuardTour.G0.Tour.T0

Start and stop the tour

http://myserver/axis-cgi/param.cgi?action=update&GuardTour.G0.Running=yes

http://myserver/axis-cgi/param.cgi?action=update&GuardTour.G0.Running=no

Guard tour parameters

The parameters in the dynamic GuardTour.G# group define a guard tour. This group is for guard tours that are set up using preset positions.

Template

guardtour

Access control — Create

admin, operator

Access control — Delete

admin, operator

Group range

0 – 9

The # in GuardTour.G# is replaced by an integer starting from zero.

Tour parameters

The parameters in the GuardTour.G#.Tour.T# group define the preset positions used in the tour.

Template

tour

Access control — Create

admin, operator

Access control — Delete

admin, operator

Group range

0 – 99

The #:s in GuardTour.G#.Tour.T# are replaced by integers starting from zero, for example GuardTour.G3.Tour.T0.

A recorded tour is a guard tour which is set up by recording PTZ movements. While recording the tour, the user steers the camera using an input device, such as a joystick, mouse, keyboard or application. The tour will play the recorded sequence of PTZ movements.

The Recorded tour API consists of the following CGIs:

Identification

Maximum number of recorded tours

The recordedtour/getschemaversions.cgi returns a list of supported versions of the XML Schemas for the Recorded Tour API and whether the schemas are deprecated or not.

Request

Access control

admin, operator, viewer

Method

GET

http://<servername>/axis-cgi/recordedtour/getschemaversions.cgi

This CGI has no arguments.

Response

Responses to recordedtour/getschemaversions.cgi

The XML Schema is available at http://www.axis.com/vapix/http_cgi/recordedtour1.xsd

HTTP Code

200 OK

Content-Type

text/xml

<?xml version="1.0" encoding="utf-8"?>
<RecordedTourResponse  
    xmlns="http://www.axis.com/vapix/http_cgi/recordedtour1"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
    xsi:SchemaLocation="http://www.axis.com/vapix/http_cgi/recordedtour1 
    http://www.axis.com/vapix/http_cgi/recordedtour1.xsd"
    SchemaVersion="1.0">
  <Success>
    <GetSchemaVersionsSuccess>
      <SchemaVersion>
        <VersionNumber>[major1].[minor1]</VersionNumber>
        <Deprecated>[deprecated]</Deprecated>
      </SchemaVersion>
      ...
    </GetSchemaVersionsSuccess>
  </Success>
</RecordedTourResponse>

Supported elements, attributes and values:

The recordedtour/list.cgi is used to list recorded tours.

Request

Access control

admin, operator, viewer

Method

POST

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

Supported arguments and values:

Response

Responses to recordedtour/list.cgi

The XML Schema is available at http://www.axis.com/vapix/http_cgi/recordedtour1.xsd

Success:

HTTP Code

200 OK

Content-Type

text/xml

<?xml version="1.0" encoding="utf-8"?>
<RecordedTourResponse  
    xmlns="http://www.axis.com/vapix/http_cgi/recordedtour1"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
    xsi:SchemaLocation="http://www.axis.com/vapix/http_cgi/recordedtour1
    http://www.axis.com/vapix/http_cgi/recordedtour1.xsd"
    SchemaVersion="1.0">
  <Success>
    <ListSuccess>
      <RecordingInformation>
        <RecordingId>[Recorded Tour ID]</RecordingId>
        <NiceName>[Recorded tour name]</NiceName>
        <Status>[Recorded tour status]</Status>
        <Camera>[Video channel]</Camera>
        <DefaultLoopDelay>[Time]</DefaultLoopDelay>
      </RecordingInformation>
      ...
    </ListSuccess>
  </Success>
</RecordedTourResponse>

Supported elements, attributes and values:

Error: See Error responses.

The recordedtour/record.cgi is used to start a tour recording. Any running guard tour on the selected video channel will be stopped when a tour recording is started.

To stop the recording, use recordedtour/stoprecording.cgi, see Stop recording.

Request

Access control

admin, operator

Method

POST

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

Supported arguments and values:

Response

Responses to recordedtour/record.cgi

The XML Schema is available at http://www.axis.com/vapix/http_cgi/recordedtour1.xsd

Success: The ID of the recorded tour is returned.

HTTP Code

200 OK

Content-Type

text/xml

<?xml version="1.0" encoding="utf-8"?>
<RecordedTourResponse  
    xmlns="http://www.axis.com/vapix/http_cgi/recordedtour1"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
    xsi:SchemaLocation="http://www.axis.com/vapix/http_cgi/recordedtour1
    http://www.axis.com/vapix/http_cgi/recordedtour1.xsd"
    SchemaVersion="1.0">
  <Success>
    <RecordSuccess>
      <RecordingId>[Recorded Tour ID]</RecordingId>
    </RecordSuccess>
  </Success>
</RecordedTourResponse>

Supported elements, attributes and values:

Error: See Error responses.

The recordedtour/stoprecording.cgi is used to stop an ongoing recording.

Request

Access control

admin, operator

Method

POST

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

Supported arguments and values:

Response

Responses to recordedtour/stoprecording.cgi

The XML Schema is available at http://www.axis.com/vapix/http_cgi/recordedtour1.xsd

Success: See General success response.

Error: See Error responses.

The recordedtour/play.cgi is used to play a recorded tour. Any ongoing playback on the selected video channel will be stopped if a new playback is started. Other PTZ operations will be stopped if their priority is lower than the recorded tour’s priority. For more information about priorities and the PTZ control queue, see VAPIX® Pan/tilt/zoom API.

Playback cannot be started while a tour is recorded.

Request

Access control

admin, operator, viewer with PTZ control access

Method

POST

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

Supported arguments and values:

Response

Responses to recordedtour/play.cgi

The XML schema is available at http://www.axis.com/vapix/http_cgi/recordedtour1.xsd

Success: See General success response.

Error: See Error responses.

The recordedtour/stopplayback.cgi is used to stop playback of a recorded tour.

Request

Access control

admin, operator, viewer with PTZ control access

Method

POST

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

Supported arguments and values:

Response

Responses to recordedtour/stopplayback.cgi

The XML schema is available at http://www.axis.com/vapix/http_cgi/recordedtour1.xsd

Success: See General success response.

Error: See Error responses.

The recordedtour/pause.cgi is used to pause playback of a recorded tour.

Use recordedtour/resume.cgi to resume playback.

Request

Access control

admin, operator, viewer with PTZ control access

Method

POST

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

Supported arguments and values:

Response

Responses to recordedtour/pause.cgi

The XML schema is available at http://www.axis.com/vapix/http_cgi/recordedtour1.xsd

Success: See General success response.

Error: See Error responses.

The recordedtour/resume.cgi is used to resume playback of a paused recorded tour.

Request

Access control

admin, operator, viewer with PTZ control access

Method

POST

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

Supported arguments and values:

Response

Responses to recordedtour/resume.cgi

The XML schema is available at http://www.axis.com/vapix/http_cgi/recordedtour1.xsd

Success: See General success response.

Error: See Error responses.

The recordedtour/modify.cgi is used to modify an existing recorded tour. The tour name and the loop delay can be modified. The tour must be inactive, that is, recording and playback must be stopped before the tour can be modified.

Request

Access control

admin, operator

Method

POST

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

Supported arguments and values:

Response

Responses to recordedtour/modify.cgi

The XML schema is available at http://www.axis.com/vapix/http_cgi/recordedtour1.xsd

Success: See General success response.

Error: See Error responses.

The recordedtour/remove.cgi is used to remove a recorded tour. The tour must be inactive, that is, recording and playback must be stopped before the tour can be removed.

Request

Access control

admin, operator

Method

POST

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

Supported arguments and values:

Response

Responses to recordedtour/remove.cgi

The XML schema is available at http://www.axis.com/vapix/http_cgi/recordedtour1.xsd

Success: See General success response.

Error: See Error responses.

The following error responses can be returned by the Recorded tour API.

HTTP code

200 OK

Content-type

text/xml

<?xml version="1.0" encoding="utf-8"?>
<RecordedTourResponse  
    xmlns="http://www.axis.com/vapix/http_cgi/recordedtour1"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
    xsi:SchemaLocation="http://www.axis.com/vapix/http_cgi/recordedtour1
    http://www.axis.com/vapix/http_cgi/recordedtour1.xsd"
    SchemaVersion="1.0">
  <GeneralError>
    <ErrorCode>[Error code]</ErrorCode>
    <ErrorDescription>[Error description]</ErrorDescription>
  </GeneralError>
</RecordedTourResponse>

Supported elements, attributes and values:

HTTP code

200 OK

Content-type

text/xml

<?xml version="1.0" encoding="utf-8"?>
<RecordedTourResponse  
    xmlns="http://www.axis.com/vapix/http_cgi/recordedtour1"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
    xsi:SchemaLocation="http://www.axis.com/vapix/http_cgi/recordedtour1
    http://www.axis.com/vapix/http_cgi/recordedtour1.xsd"
    SchemaVersion="1.0">
  <Success>
    <GeneralSuccess>
    </GeneralSuccess>
  </Success>
</RecordedTourResponse>

Supported elements, attributes and values:

This example shows how to set up an action rule that runs a guard tour Monday through Friday from 7 a.m. to 7 p.m.

The action rule is created in three steps:

The action rule is created in three steps:

1. Create a scheduled event using AddScheduledEvent.

2. Create a guard tour action configuration using AddActionConfiguration.

3. Create an action rule using AddActionRule. The action rule uses the Scheduled Event ID scheduledEventId returned by AddScheduledEvent and the Action Configuration ID actionId returned by AddActionConfiguration.

The examples are written in C# and use the helper functions defined in section Helper functions.

Step 1: Create a scheduled event that runs Monday through Friday from 7 a.m. to 7 p.m.

// Create the web service client.
EventClient client = CreateEventServiceClient("<address>", "<username>", "<password>");
 
try
{
  // Create the scheduled event.
  NewScheduledEvent scheduledEvent = new NewScheduledEvent
  {
    Name = "My schedule",
    Schedule = new Schedule
    {
      ICalendar = new ICalendar
      {
        Value =
          "DTSTART:20111212T07:00 " +
          "DTEND:20111212T19:00 " +
          "RRULE:FREQ=WEEKLY;BYDAY=MO,TU,WE,TH,FR"
      }
    }
  };
 
  // Add the scheduled event.
  string scheduledEventId = client.AddScheduledEvent(scheduledEvent);
}
catch (Exception e)
{
  HandleException(e);
}

Step 2: Create an action configuration that starts the guard tour. The guard tour action used here is unlimited, that is, the guard tour will keep running as long as the action rule conditions are fulfilled.

ActionClient client = CreateActionServiceClient("<address>", "<username>", "<password>");
 
try
{
  // Verify that the camera supports the action.
  ActionTemplate[] actiontemplates = client.GetActionTemplates();
  if (actiontemplates.Any(               
    template => template.TemplateToken == "com.axis.action.unlimited.guardtour") == false)        
  {
    // Camera does not support the guard tour action.
    return;
  }
 
  // Create guard tour action
  NewActionConfiguration newAction = new NewActionConfiguration
  {
    TemplateToken = "com.axis.action.unlimited.guardtour",
    Parameters = new ActionParameters
    {
      Parameter = new[]
      {
        new ActionParameter { Name = "tour_id", Value = "0" }
        new ActionParameter { Name = "goto_home", Value = "1" }
        new ActionParameter { Name = "channel", Value = "0" }
      }
    }
  };
 
  // Add the action to the camera.
  string actionId = client.AddActionConfiguration(newAction);
}
catch (Exception e)
{
  HandleException(e);
}

Step 3: Create the action rule. The scheduled event is used as condition and the action configuration is used as the primary action.

ActionClient client = CreateActionServiceClient("<address>", "<username>", "<password>");
 
try
{
  // Create action rule
  NewActionRule newActionRule = new NewActionRule
  {
    Name = "Run daily guard tour",
    Conditions = new[]
    {
      FormatTopicExpression(
        "tns1:UserAlarm/tnsaxis:Recurring/tnsaxis/Interval",
        "boolean(//SimpleItem[@Name=\"id\" and @Value=\"scheduledEventId\"]) and "
        + "boolean(//SimpleItem[@Name=\"active\" and @Value=\"1\"])")
      },
    PrimaryAction = actionId,
    Enabled = true
  };
 
  // Add the action rule to the camera.
  string actionRuleId = client.AddActionRule(newActionRule);
}
catch (Exception e)
{
  HandleException(e);
}

Use the guard tour action to start a guard tour (preset tour).

The action can be run as:

The action can be run as:

• fixed action — run the guard tour once

• unlimited action — keep the guard tour running as long as all conditions are fulfilled

Action ID

com.axis.action.fixed.guardtour

Action ID

com.axis.action.unlimited.guardtour

Use the recorded tour action to start a recorded tour. The action is unlimited; the recorded tour keeps running as a long as all conditions are fulfilled.

Action ID

com.axis.action.unlimited.recordedtour