Application configuration API

Description

VAPIX® Axis Application Configuration API is used to configure applications developed by Axis, for example AXIS Video Motion Detection and AXIS Cross Line Detection.

Supported functionality:

Get the application configuration. See Get application configuration.
Modify the application configuration. Modify application configuration.
Obsolete: List installed applications. This operation might be removed in the future. Replaced by applications\list.cgi in VAPIX® Application API.

Identification

Property: Properties.EmbeddedDevelopment.Version=1.00 or later
Firmware: 5.11 or later

Dependencies

Applications are uploaded and controlled using VAPIX® Application API.

Obsoletes

The list operation vaconfig.cgi?action=list is obsolete and should not be used.

This operation is replaced by applications\list.cgi in VAPIX® Application API.

Common examples

These examples demonstrate how to use VAPIX® Axis Application Configuration API. Everything marked in bold should be replaced by application-specific values.

Get the application configuration.

Request:


http://myserver/axis-cgi/vaconfig.cgi?action=get&name=ExampleApp

Response:

<reply result="ok">
  <config version="1.0">
    <application name="ExampleApp">
      <ruleEngine>
        <namedObjects>
          <namedObject name="ExampleLine1">
            <data knownNameType="geometry.segment">
              <segment>
                <point x="-0.5" y="0.0"/>
                <point x="0.5" y="0.0"/>
              </segment>
            </data>
          </namedObject>
          <namedObject name="ExamplePolygon1">
            <data knownNameType="geometry.polygon">
              <polygon>
                <point x="0.60" y="0.60"/>
                <point x="0.60" y="-0.60"/>
                <point x="-0.60" y="-0.60"/>
                <point x="-0.60" y="0.60"/>
              </polygon>
            </data>
          </namedObject>
        </namedObjects>
        <rules>
          <rule name="example_rule" function="example_function">
            <parameter name="ExampleLineParameter" value="ExampleLine1"/>
            <parameter name="ExamplePolygonParameter" value="ExamplePolygon1"/>
          </rule>
        </rules>
        <scripts>
          <script encryption="1">example.lua</script>
        </scripts>
        <events>
          <event name="example_event">
            <attr key="example_state" nicename="Example State" tag="property_state"/>
          </event>
        </events>
        <moteConfig>
          <option name="boundingBox" value="false"/>
          <option name="polygon" value="true"/>
          <option name="velocity" value="true"/>
        </moteConfig>
      </ruleEngine>
    </application>
  </config>
</reply>

Modify the application configuration.

Request:

POST http://myserver/axis-cgi/vaconfig.cgi HTTP/1.0
Content-Type: application/x-www-form-urlencoded
Content-Length: <content length>
 
action=modify&name=ExampleApp
<config version="1.0">
  <application name="ExampleApp">
    <ruleEngine>
      <namedObjects>
        <namedObject name="ExampleLine1">
          <data knownNameType="geometry.segment">
            <segment>
              <point x="-0.5" y="0.0"/>
              <point x="0.5" y="0.0"/>
            </segment>
          </data>
        </namedObject>
        <namedObject name="ExamplePolygon1">
          <data knownNameType="geometry.polygon">
            <polygon>
              <point x="0.60" y="0.60"/>
              <point x="0.60" y="-0.60"/>
              <point x="-0.60" y="-0.60"/>
              <point x="-0.60" y="0.60"/>
            </polygon>
          </data>
        </namedObject>
      </namedObjects>
      <rules>
        <rule name="example_rule" function="example_function">
          <parameter name="ExampleLineParameter" value="ExampleLine1"/>
          <parameter name="ExamplePolygonParameter" value="ExamplePolygon1"/>
        </rule>
      </rules>
      <scripts>
        <script encryption="1">example.lua</script>
      </scripts>
      <events>
        <event name="example_event">
          <attr key="example_state" nicename="Example State" tag="property_state"/>
        </event>
      </events>
      <moteConfig>
        <option name="boundingBox" value="false"/>
        <option name="polygon" value="true"/>
        <option name="velocity" value="true"/>
      </moteConfig>
    </ruleEngine>
  </application>
</config>
</reply>

Example of an event emitted from the application. Application-specific content is marked in bold, the rest is part of the ONVIF stream and defined in ONVIF core specification version 1.0.

<tt:MetadataStream xmlns:tt="http://www.onvif.org/ver10/schema">
  <tt:Event xmlns:tt="http://www.onvif.org/ver10/schema">
    <wsnt:NotificationMessage
        xmlns:tns1="http://www.onvif.org/ver10/topics"
        xmlns:tnsaxis="http://www.axis.com/2009/event/topics"
        xmlns:wsnt="http://docs.oasis-open.org/wsn/b-2"
        xmlns:wsa5="http://www.w3.org/2005/08/addressing">
      <wsnt:Topic Dialect="http://docs.oasis-open.org/wsn/t-1/TopicExpression/Simple">
        tns1:RuleEnginge/tnsaxis:ExampleApp/example_event
      </wsnt:Topic>
      <wsnt:ProducerReference>
        <wsa5:Address>
          uri://daf20c8-c41f-11e0-8c89-00408cb96106/ProducerReference
        </wsa5:Address>
      </wsnt:ProducerReference>
      <wsnt:Message>
        <tt:Message UtcTime="2012-03-07T13:44:34.112703Z" PropertyOperation="Initialized"
          <tt:Source>
          </tt:Source>
          <tt:Key>
          </tt:Key>
          <tt:Data>
            <tt:SimpleItem Name="example_state" Value="0"/>
          </tt:Data>
        </tt:Message
      </wsnt:Message>
    </wsnt:NotificationMessage>
  </tt:Event>
</tt:MetadataStream>

Application configuration

The application configuration is an XML file stored in the Axis product. If the application configuration is modified, the file is replaced by a new configuration file.

If the application configuration is modified while the application is running, the application will be restarted with the new configuration.

The application cannot be started if it is not possible to parse the XML file. If the application configuration is malformed, but still parsable, the application may not work properly or may fail to run.

XML Application Setup Data Description

The application configuration is defined in XML format. Most parts define how the application shall run and should not be modified.

For description of the application configuration for a particular application, see the documentation provided with the application.

XML path	Attribute	Valid values	Description
`application/ruleEngine/namedObjects`			Section with all named objects used by the application.
`application/ruleEngine/rules`			Section will all rules used by the application.
`application/ruleEngine/rules/rule`	`name`	String	Name of the rule.
`application/ruleEngine/rules/rule`	`function`	String	Name of the rule function used to execute the rule. The function which is defined in a script file (see scripts section), is executed with the provided parameter values as input.
`application/ruleEngine/rules/rule/parameter`	`name`	String	Name of a paramer used by the rule function.
`application/ruleEngine/rules/rule/parameter`	`value`	String	Value of a parameter used by the rule function.
`application/ruleEngine/scripts`			Section with scripts used by the application.
`application/ruleEngine/scripts/script`		String	Name of a script file used by the application.
`application/ruleEngine/scripts/script`	`encryption`	`0` `1`	`1` = The script is encrypted. `0` = The script is not encrypted.
`application/ruleEngine/events`			Section with all events used by the application.
`application/ruleEngine/events/event`	`name`	String	Name of an event emitted by the application.
`application/ruleEngine/events/event/attr`	`key`	String	Key string for the event.
`application/ruleEngine/events/event/attr`	`tag`	`source` `data` `property-state`	`source` = This is source information in the event metadata. `data` = This is data information in the event metadata. `property-state` = This is a stateful event. The current state is `0` or `1`.
`application/ruleEngine/moteConfig`			Section with all MOTE configuration options. Different applications may have different MOTE configuration.
`application/ruleEngine/moteConfig/option`	`name`	`boundingBox`	Name of the MOTE configuration option.
`application/ruleEngine/moteConfig/option`	`value`	`true` `false`	`true` = Bounding box should be used. `false` = Bounding box should not be used.
`application/ruleEngine/moteConfig/option`	`name`	`polygon`	Name of the MOTE configuration option.
`application/ruleEngine/moteConfig/option`	`value`	`true` `false`	`true` = Polygon should be used. `false` = Polygon should not be used.
`application/ruleEngine/moteConfig/option`	`name`	`velocity`	Name of the MOTE configuration option.
`application/ruleEngine/moteConfig/option`	`value`	`true` `false`	`true` = Velocity should be used. `false` = Velocity should not be used.

HTTP API

Manage I/O ports - port.cgi

Use io/port.cgi to retrieve information about port status and directions, to activate and deactivate ports and to monitor ports.

Important

In port.cgi requests and in all responses, port numbering (Port ID below) starts from one (where one corresponds to the physical port labeled ‘1’).

Security level: viewer
Method: GET

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

With the following arguments and values:

Argument	Valid values	Description
`check=<int>[,<int>,...]`	`<Port ID 1>[<Port ID 2>,...]`	Return the status (1 or 0) of one or more ports numbered <`Port ID 1`>, <Port ID 2>, ... `1` = Closed circuit. `0` = Open circuit.
`checkactive=<int>` `[,<int>,...]`	`<Port ID 1>[,Port ID 2>,...]`	Return the status (`active` or `inactive`) of one or more ports numbered `<Port ID 1>`, `<Port ID 2>`, ... This value depends on the parameters `Output.Active` for an output and `Input.Trig` for an input. If the port is an output and `Output.Active` is configured as closed, then this request will return active if the port state is closed. The same goes for an input port that has `Input.Trig` configured as closed.
`checkdirection=<int>` `[,<int>,...]`	`<Port ID 1>[,<Port ID 2>,...]`	Return the port direction (input or output) of one or more ports numbered `<Port ID 1>`, `<Port ID 2>`,...
`monitor=<int>[,<int>,...]`⁽¹⁾	`<Port ID 1>[,Port ID 2>,...]`	Return a multipart stream of “check” ports (see return description below). Input and output ports must be monitored separately.
`action=<string>`⁽²⁾	`[<Port ID>]:<a>[<wait><a>...]`	Activate or deactivate an output. Use the `<wait>` option to activate/deactivate the port for a limited period of time. `<Port ID>` = Port number. If omitted, output 1 is selected. `<a>` = Action character. `/`=active, `\`=inactive `<wait>` = Delay before the next action. Unit: milliseconds Note: The `:`, `/` and `\` characters must be percent-encoded in the URI. See . Example: To set output 1 to active, use `1:/`. In the URI, the action argument becomes `action=1%3A%2F`

Outputs and inputs must be monitored separately.
Valid for output ports only.

Example 1:

Retrieve information about port 1.

http://myserver/axis-cgi/param.cgi?action=list&group=IOPort.I0

Response

HTTP code: 200 OK
Content-type: text/plain

root.IOPort.I0.Configurable=yes
root.IOPort.I0.Direction=output
root.IOPort.I0.Input.Name=Input 1
root.IOPort.I0.Input.Trig=closed
root.IOPort.I0.Output.Name=Output 1
root.IOPort.I0.Output.Active=open
root.IOPort.I0.Output.Button=actinact
root.IOPort.I0.Output.PulseTime=0

Example 2:

Configure port 2 to act as output. This example is only applicable to configurable ports.

http://myserver/axis-cgi/param.cgi?action=update&IOPort.I2.Direction=output

Example 3:

Set port 2 to active, wait 300 ms and then set the port to inactive. Some characters in the action argument action=2:/300\ must be percent-encoded.

http://myserver/axis-cgi/io/port.cgi?action=2%3A%2F300%5C

Successful request, all arguments except monitor

Response

HTTP code: 200 OK
Content-type: text/plain

<Port ID>=<information>

Note

The body is empty for the action argument.

Successful request, argument monitor

Response

HTTP code: 200 OK
Content-type: multipart/x-mixed-replace; boundary=<boundary>

Body:

--<boundary>
<monitor data>

Where the returned <monitor data> is:

<Port ID><port direction>:<action character>
 
--<boundary>
<monitor data>

Here <id> is the port and <port direction> is I for inputs and O for outputs. The action character is / or H for active and \ or L for inactive ports. The characters / and \ indicates a change in the state. The characters H and L indicates that the state is unchanged.

Note

Non-empty boundaries are sent when the port status changes. If there are no changes, empty boundaries are sent at 15-second intervals.

Get application configuration

Use vaconfig.cgi?action=get to retrieve the application configuration.

Access control: admin, operator
Method: GET

Syntax

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

with the following arguments and values

Argument	Valid values	Description
`action=<string>`	`get`	Get the application configuration in XML format.
`name=<string>`	String	Application name.

Response
HTTP Code: 200 OK
Content-Type: text/xml

Body:

<reply result="ok">
  <config version="1.0">
    [application xml configuration]
  </config>
</reply>

For a description of the application configuration, see the API documentation for the application.

For error responses, see Error responses.

Modify application configuration

Use vaconfig.cgi?action=modify to modify the application configuration.

Access control: admin, operator
Method: POST

Syntax

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

Argument	Valid values	Description
`action=<string>`	`modify`	Modify the application configuration in XML format.
`name=<string>`	String	Application name.

Body:

POST http://myserver/axis-cgi/vaconfig.cgi HTTP/1.0
Content-Type: application/x-www-form-urlencoded
Content-Length: <content-length>
  
action=modify&name=[application name]
<config version="1.0">
  [application xml configuration]
</config>

Response
HTTP Code: 200 OK
Content-Type: text/xml

Body:

<reply result="ok" />

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

For error responses, see Error responses.

List installed applications

Important

The vaconfig.cgi?action=list is obsolete and should not be used. Replaced by applications\list.cgi in VAPIX® Application API.

vaconfig.cgi?action=list lists the installed applications.

Access control: admin, operator
Method: GET

Syntax

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

with the following arguments and values:

Argument	Valid values	Description
`action`	`list`	List the installed applications.

Response
HTTP Code: 200 OK
Content-Type: text/xml

Body:

<reply result="ok">
  <application name="[Application name]"/>
  <application name="[Application name]"/>
  ...
<reply>

XML Schema: http://www.axis.com/vapix/http_cgi/vaconfig/list1.xsd.

For error responses, see Error responses.

Error responses

If the requested operation cannot be executed, the type of error and an error message will be returned.

Return
HTTP Code: 200 OK
Content-Type: text/xml

Body:

<reply result="error">
  <error type="<Error type>" message="<Error message>"/>
</reply>

Error type	Description
`bad_request`	Bad request. The request URL was not formatted correctly.
`no_such_application`	There is no application with the given `name`.
`internal`	The action could not be performed. This is for example returned if the application fails to restart after a configuration modification.

Get RTSP stream with event topic filter

Retrieve an RTSP stream with an event topic filter.

Access control: admin, operator
Method: GET

Syntax:

rtsp://<servername>/axis-media/media.amp?<argument>=<value>[&<argument>=<value>...]

Argument	Valid values	Description
`video`	`0` `1`	Specify whether video should be available in the stream. `0` = no video `1`= video
`event`	`on` `off`	Specify whether event metadata should be available in the stream. `on` = event metadata is included `off` = event metadata is not included
`eventtopic`	String	The event topic filter to include. For AXIS Video Motion Detection 3, use `onvif:RuleEngine/axis:VMD3//.` For AXIS Video Motion Detection 2.1 use `onvif:RuleEngine/axis:VideoMotionDetection//motion` For AXIS Digital Autotracking, use `onvif:RuleEngine/axis:DigitalAutotracking/tracking//.` For AXIS Cross Line Detection 1.1, use `onvif:RuleEngine/axis:CrossLineDetection//.`
For additional arguments, see Network Video > Video Streaming > Video streaming Over RTSP > Parameter Specification RTSP URL in VAPIX Library.