Shock detection API

Description

Shock detection is available in Axis products with built-in orientation devices such as accelerometers or gyroscopes. When shock detection is enabled, the camera’s position and acceleration is monitored. If the camera is tilted or displaced from its current position, or if the camera is subject to punches, hard blows or similar, an alarm is triggered and the Axis product emits a shock detection event.

The alarm is triggered immediately when the camera is punched or displaced. There is no pre-trigger time. After the alarm, position and acceleration monitoring continues from the camera’s new position. To prevent multiple events for the same displacement, a new shock detection event will not be emitted until 5 seconds has passed.

Shock detection sensitivity can be set to an integer between 0 and 100. Low sensitivity means that a hit must be quite powerful to trigger an alarm. High sensitivity means that very small displacements, including vibrations, will be trigger alarms.

The Shock detection API is used to enable, disable and adjust the Axis product’s shock detection functionality.

Supported functionality:

• Enable and disable shock detection
• Control the sensitivity level

Identification

VAPIX Shock detection API is available if

• Property: root.Properties.Tampering.ShockDetection=yes
• Firmware: 5.50 and later

Common examples

Retrieve supported XML schema versions.

Request:

http://<servername>/axis-cgi/shockdetection/getschemaversion.cgi

Response:

HTTP/1.0 200 OK
Content-type: text/xml

<?xml version="1.0" encoding="utf-8"?>
<ShockDetectionResponse xmlns="http://www.axis.com/vapix/http_cgi/shockdetection1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.axis.com/vapix/http_cgi/shockdetection1 http://www.axis.com/vapix/http_cgi/shockdetection1" SchemaVersion="1.0">
  <Success>
    <GetSchemaVersionsSuccess>
      <SchemaVersion>
        <VersionNumber>1.0</VersionNumber>
        <Deprecated></Deprecated>
      </SchemaVersion>
    </GetSchemaVersionsSuccess>
  </Success>
</ShockDetectionResponse>

Enable shock detection in the Axis product.

Request:

http://<servername>/axis-cgi/shockdetection/setenabled.cgi?schemaversion=1&enabled=true

Check if shock detection is enabled.

Request:

http://<servername>/axis-cgi/shockdetection/getenabled.cgi?schemaversion=1

Response:

HTTP/1.0 200 OK
Content-type: text/xml

<?xml version="1.0" encoding="UTF-8"?>
<ShockDetectionResponse xmlns="http://www.axis.com/vapix/http_cgi/shockdetection1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.axis.com/vapix/http_cgi/shockdetection1 http://www.axis.com/vapix/http_cgi/shockdetection1" SchemaVersion="1.0">
  <Success>
    <GetEnabledSuccess>
      <Enabled>true</Enabled>
    </GetEnabledSuccess>
  </Success>
</ShockDetectionResponse>

Set shock detection sensitivity to 60.

Request:

http://<servername>/axis-cgi/shockdetection/setsensitivitylevel.cgi?schemaversion=1&level=60

Retrieve the shock detection sensitivity level.

Request:

http://<servername>/axis-cgi/shockdetection/getsensitivitylevel.cgi?schemaversion=1

Response:

HTTP/1.0 200 OK
Content-type: text/xml

<?xml version="1.0" encoding="UTF-8"?>
<ShockDetectionResponse xmlns="http://www.axis.com/vapix/http_cgi/shockdetection1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.axis.com/vapix/http_cgi/shockdetection1 http://www.axis.com/vapix/http_cgi/shockdetection1" SchemaVersion="1.0">
  <Success>
    <GetSensitivityLevelSuccess>
      <SensitivityLevel>
        <Level>60</Level>
      </SensitivityLevel>
    </GetSensitivityLevelSuccess>
  </Success>
</ShockDetectionResponse>

Check if enabled

Use shockdetection/getenabled.cgi to check if shock detection is enabled.

Request

• Access control: admin, operator
• Method: GET

Syntax:

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

with the following arguments and values:

Argument	Valid values	Description
schemaversion=<integer>	Integer	Required. The major version of the XML Schema to use for the response. See XML schemas.

Response

Responses from shockdetection/getenabled.cgi

Success

A successful request returns true is shock detection is enabled and false if shock detection is disabled.

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

Body:

<?xml version="1.0" encoding="utf-8"?>
<ShockDetectionResponse xmlns="http://www.axis.com/vapix/http_cgi/shockdetection1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.axis.com/vapix/http_cgi/shockdetection1 http://www.axis.com/vapix/http_cgi/shockdetection1" SchemaVersion="1.0">
  <Success>
    <GetEnabledSuccess>
      <Enabled>[true | false]</Enabled>
    </GetEnabledSuccess>
  </Success>
</ShockDetectionResponse>

Supported elements, attributes and values:

Element	Description
ShockDetectionResponse	Contains the response. For information about XML schema versions, see XML schemas.
GetEnabledSuccess	Successful request.
Enabled	true = Shock detection is enabled.false = Shock detection is disabled.

Error

If an error occurred, a GeneralError response is returned. See General error response.

Error codes: 10, 20, 40

Enable shock detection

Use shockdetection/setenabled.cgi to enable and disable shock detection.

Request

• Access control: admin, operator
• Method: GET

Syntax:

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

with the following arguments and values:

Argument	Valid values	Description
schemaversion=<integer>	Integer	Required. The major version of the XML Schema to use for the response. See XML schemas.
enabled=<boolean>	true false	true = Enable shock detection.false = Disable shock detection.

Response

Responses from shockdetection/setenabled.cgi

Success

If the request is successful, shock detection is enabled and a GeneralSuccess response is returned. See General success response.

Error

If an error occurred, a GeneralError response is returned. See General error response.

Error codes: 10, 20, 40

Get sensitivity level

Use shockdetection/getsensitivitylevel.cgi to retrieve the current sensitivity level.

Request

• Access control: admin, operator
• Method: GET

Syntax:

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

with the following arguments and values:

Argument	Valid values	Description
schemaversion=<integer>	Integer	Required. The major version of the XML Schema to use for the response. See XML schemas.

Response

Responses from shockdetection/getsensitivitylevel.cgi

Success

A successful request returns the current sensitivity level.

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

Body:

<?xml version="1.0" encoding="utf-8"?>
<ShockDetectionResponse xmlns="http://www.axis.com/vapix/http_cgi/shockdetection1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.axis.com/vapix/http_cgi/shockdetection1 http://www.axis.com/vapix/http_cgi/shockdetection1" SchemaVersion="1.0">
  <Success>
    <GetSensitivityLevelSuccess>
      <SensitivityLevel>
        <Level>[level]</Level>
      </SensitivityLevel>
    </GetSensitivityLevelSuccess>
  </Success>
</ShockDetectionResponse>

Supported elements, attributes and values:

Element	Description
ShockDetectionResponse	Contains the response. For information about XML schema versions, see XML schemas.
GetSensitivityLevelSuccess	Successful request
SensitivityLevel	Contains the sensitivity level.
Level	Integer defining the sensitivity level.

Error

If an error occurred, a GeneralError response is returned. See General error response.

Error codes: 10, 20, 40

Set sensitivity level

Use shockdetection/setsensitivitylevel.cgi to set the shock detection sensitivity level.

Shock detection sensitivity can be set to an integer between 0 and 100. Low sensitivity means that a hit must be quite powerful to trigger an alarm. High sensitivity means that very small displacements, including vibrations, will be trigger alarms.

Request

• Access control: admin, operator
• Method: GET

Syntax:

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

with the following arguments and values:

Argument	Valid values	Description
schemaversion=<integer>	Integer	Required. The major version of the XML Schema to use for the response. See XML schemas.
level=<integer>	0 .. 100	The shock detection sensitivity level.0 = Low sensitivity100 = High sensitivity

Response

Responses from shockdetection/setsensitivitylevel.cgi

Success

If the request is successful, the sensitivity level is set to the submitted value and a GeneralSuccess response is returned. See General success response.

Error

If an error occurred, a GeneralError response is returned. See General error response.

Error codes: 10, 20, 30, 40

Get schema versions

Use shockdetection/getschemaversion.cgi to retrieve the supported XML schema versions.

Request

• Access control: admin, operator
• Method: GET

Syntax:

http://<servername>/axis-cgi/shockdetection/getschemaversion.cgi

This CGI has no arguments

Response

Responses from shockdetection/getschemaversion.cgi

Success

A successful request returns the supported schema version.

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

Body:

<?xml version="1.0" encoding="utf-8"?>
<ShockDetectionResponse xmlns="http://www.axis.com/vapix/http_cgi/shockdetection1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.axis.com/vapix/http_cgi/shockdetection1 http://www.axis.com/vapix/http_cgi/shockdetection1" SchemaVersion="1.0">
  <Success>
    <GetSchemaVersionsSuccess>
      <SchemaVersion>
        <VersionNumber>[major.minor]</VersionNumber>
        <Deprecated>[true/false]</Deprecated>
      </SchemaVersion>
    </GetSchemaVersionsSuccess>
  </Success>
</ShockDetectionResponse>

Supported elements, attributes and values:

Element	Description
ShockDetectionResponse	Contains the response. For information about XML schema versions, see XML schemas.
GetSchemaVersionsSuccess	Successful request
SchemaVersion	Contains the schema version
VersionNumber	Schema version in format major.minor where major is the major version and minor the minor version.
Deprecated	If true, this version of the XML Schema is deprecated and should not be used.Default: false

Error

If an error occurred, a GeneralError response is returned. See General error response.

Error codes: 10, 20, 40

General success response

General success response in Shock Detection API.

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

Body:

<?xml version="1.0" encoding="UTF-8"?>
<ShockDetectionResponse xmlns="http://www.axis.com/vapix/http_cgi/shockdetection1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.axis.com/vapix/http_cgi/shockdetection1 http://www.axis.com/vapix/http_cgi/shockdetection1" SchemaVersion="1.0">
  <Success>
    <GeneralSuccess></GeneralSuccess>
  </Success>
</ShockDetectionResponse>

Supported elements, attributes and values:

Element	Description
ShockDetectionResponse	Contains the response. For information about XML schema versions, see XML schemas.
Success	Successful request
GeneralSuccess	Successful request

General error response

General error response in Shock detection API.

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

Body:

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

Supported elements, attributes and values:

Element	Description
ShockDetectionResponse	Contains the response. For information about XML schema versions, see XML schemas.
GeneralError	Error
ErrorCode	A numeric error code. See table below.
ErrorDescription	Description of the error

Error code	Description	CGI
10	Error while processing the request.	All
20	Invalid request.	All
30	Unable to set shock detection sensitivity. Specified value is out of range.	setsensitivitylevel.cgi
40	Specified version is not supported.	All

Shock detection event

The shock detection event tns1:Device/tnsaxis:Tampering/ShockDetected is a stateless event.

To retrieve the event declaration, use aev:GetEventInstances.

Event declaration:

<tns1:Device aev:NiceName="Device">
  <tnsaxis:Tampering aev:NiceName="Tampering">
    <ShockDetected wstop:topic="true" aev:NiceName="Shock Detected">
      <aev:MessageInstance>
        <aev:SourceInstance>
          <aev:SimpleItemInstance aev:NiceName="Channel" Type="xsd:int" Name="channel">
            <aev:Value>1</aev:Value>
          </aev:SimpleItemInstance>
        <aev:DataInstance />
      </aev:MessageInstance>
    </ShockDetected>
  </tnsaxis:Tampering>
</tns1:Device>

The topic is tns1:Device/tnsaxis:Tampering/ShockDetected. Channel is the video channel and is intended for future use.