Radar configuration
The VAPIX® Radar configuration API consists of methods compatible with AXIS Radar Motion Detection (RMD), an application used by the Axis Radar detectors. By using the API, you will be able to:
define a guarded zone where motion can be detected.
set up and configure several motion detection zones.
configure the area rules to determine when an event should be triggered.
configure the radar detection and how it filters information in different situations.
Overview
Radar configuration is split into two separate API:s containing their own methods and parameters:
The Control API uses control.cgi as its communications interface and consists of methods that can configure the rules for event zones:
| Method | Description |
getConfiguration | Queries for the complete event configuration. |
setConfiguration | Uploads a complete event configuration. |
getConfigurationCapabilities | Queries for the configuration capabilities. |
getEnabled | Queries if the radar has been enabled. |
setEnabled | Enables or disables the radar. |
getSupportedVersions | Queries for a list of supported API versions. |
sendAlarmEvent | Sends an alarm event for testing purposes (including information about the alarm configuration and status). |
The Analytics API uses radaranalytics.cgi as its communications interface and consists of methods that handles the configuration of general parameters and application algorithms:
| Method | Description |
getConfigurationCapabilities | Queries for the configuration capabilities. |
setDetectionSensitivity | Sets the detection sensitivity value suitable for the scene. |
getDetectionSensitivity | Queries for the current sensitivity of the detection algorithm. |
setCoexistence | Sets the radar’s coexistence mode. |
getCoexistence | Queries for the current coexistence mode. |
setFrequencyChannel | Sets the frequency channel to avoid interference between two radar sensors that are mounted close to each other. |
getFrequencyChannel | Queries for the current frequency channel of the radar sensor. |
setGlobalFilters | Sets the radar’s global filter configuration. |
getGlobalFilters | Queries the current global filter configurations. |
setMountingHeight | Sets the mounting height of the security radar. |
getMountingHeight | Queries for the current mounting height. |
setMountingTilt | Sets the mounting tilt of the security radar. |
getMountingTilt | Queries for the current mounting tilt. |
getRadarDataStatus | Queries for the current status of radar data reception. |
getSupportedVersions | Queries for a list of the supported API versions. |
Identification
- API Discovery
id=radar-analytics2(radaranalytics.cgi)- API Discovery
id=radar-control2(control.cgi)
Common examples
Back up and restore configuration
This example will show you how to back up your event configurations, or restore them without having to set each individual parameter. It is possible to apply the same configuration to multiple devices as long as they have the same version of the Control API. Please note that this process may not be applied correctly when there is a difference between the major API versions and while it may work when only the minor version differs, some parameters will not.
1. Request the current radar event configuration:
http://myserver/axis-cgi/radar/control.cgi{
"apiVersion": "2.1",
"context": "<client context>",
"method": "getConfiguration"
}2. Parse the response.
{
"apiVersion": "2.1",
"context": "<client context>",
"method": "getConfiguration",
"data": {...}
}3. Restore the configuration settings by modifying the data field in the response and post it as params.
http://myserver/axis-cgi/radar/control.cgi{
"apiVersion": "2.1",
"context": "<client context>",
"method": "setConfiguration",
"params": {...}
}API References:
Configure all settings
This example will show you how to retrieve all parameters with their current configurations to change certain values and upload them back to the API.
1. Request the current radar event configuration:
http://myserver/axis-cgi/radar/control.cgi{
"apiVersion": "2.1",
"context": "<client context>",
"method": "getConfiguration"
}2. Parse the response.
{
"apiVersion": "2.1",
"context": "<client context>",
"method": "getConfiguration",
"data": {...}
}3. Modify the configuration received in the data field and upload the modified configuration as params.
http://myserver/axis-cgi/radar/control.cgi{
"apiVersion": "2.1",
"context": "<client context>",
"method": "setConfiguration",
"params": {...}
}API references:
Test event functionality
This example will show you how to test a setup consisting of multiple radars with events from different radar profiles and check if they return the expected functions.
1. Send an alarm event for profile 1.
http://myserver/axis-cgi/radar/control.cgi{
"apiVersion": "2.1",
"context": "<client context>",
"method": "sendAlarmEvent",
"params": {
"profile": 1
}
}2. Parse the successful response with an empty data object to raise a temporarily stateful alarm on the given profile.
{
"apiVersion": "2.1",
"context": "<client context>",
"method": "sendAlarmEvent"
}API references:
Determine configuration capabilities
This example will show you how to determine the default values and limits of the configuration parameters. This will be useful when you wish to update the user interface without needing to hard code the values.
1. Request the configuration capabilities of the API.
http://myserver/axis-cgi/radar/control.cgi{
"apiVersion": "2.1",
"context": "<client context>",
"method": "getConfigurationCapabilities"
}2. Parse the response.
{
"apiVersion": "2.1",
"context": "<client context>",
"method": "getConfigurationCapabilities",
"data": {...}
}API references:
Enable the minimum speed filter
This example will show you how to detect objects based on their movement speed and track objects, such as fast-moving vehicles, by setting a minimum speed limit that the object must exceed to generate an alarm.
1. Request the configuration capabilities of the API.
http://myserver/axis-cgi/radar/control.cgi{
"apiVersion": "2.1",
"context": "<client context>",
"method": "getConfigurationCapabilities"
}2. Parse the response. This will provide the capabilities in the data object.
{
"apiVersion": "2.1",
"context": "<client context>",
"method": "getConfigurationCapabilities",
"data": {
...
"filters": [
...
{
"type": "minimumSpeedLimit",
"min": 0.0,
"max": 70.0,
"default": 69.444444444444443,
"defaultActive": true
}
...
]
...
}
}3. Request the current radar event configuration.
http://myserver/axis-cgi/radar/control.cgi{
"apiVersion": "2.1",
"context": "<client context>",
"method": "getConfiguration"
}4. Parse the response. The minimum speed filter will be set to off in this example.
{
"apiVersion": "2.1",
"context": "<client context>",
"method": "getConfiguration",
"data": {
...
"profiles": [
...
"filters": [
...
{
"type": "minimumSpeedLimit",
"data": 0,
"active": false
}
...
]
]
...
}
}5. Enable the minimum speed filter by setting its properties described by the configuration capabilities. The following example will show you when the configuration is assumed to be unchanged, with the exception for the values in the minimum speed filter.
http://myserver/axis-cgi/radar/control.cgi{
"apiVersion": "2.1",
"context": "<client context>",
"method": "setConfiguration",
"params": {
...
"profiles": [
...
"filters": [
...
{
"type": "minimumSpeedLimit",
"data": 5.0,
"active": true
}
...
]
]
...
}
}6. Parse the response, which will contain an empty data response if the request is successful.
{
"apiVersion": "2.1",
"context": "<client context>",
"method": "setConfiguration",
"data": {}
}API references:
Set up a cross line
This example will show you how to generate an alarm event whenever an object crosses a pre-defined line in a specified direction.
1. Request the current configuration capabilities.
http://myserver/axis-cgi/radar/control.cgi{
"apiVersion": "2.1",
"context": "<client context>",
"method": "getConfigurationCapabilities"
}2. Parse the response, which will provide the capabilities in the data object.
{
"apiVersion": "2.1",
"context": "<client context>",
"method": "getConfigurationCapabilities",
"data": {
...
"profiles": [
...
{
"type": "crossLine",
"min": [-1, -1],
"max": [1, 1],
"minNbrVertices": 2,
"maxNbrVertices": 100000,
"minNbrInstances": 0,
"maxNbrInstances": 100000,
"alarmDirections": [
"leftToRight",
"rightToLeft"
],
"detfaultInstance": [
[-0.5, 0.0],
[0.5, 0.0]
],
"defaultAlarmDirection": "leftToRight"
}
...
]
...
}
}3. Request the current event configuration.
http://myserver/axis-cgi/radar/control.cgi{
"apiVersion": "2.1",
"context": "<client context>",
"method": "getConfigurationCapabilities"
}4. Parse the current radar event configuration.
{
"apiVersion": "2.1",
"context": "<client context>",
"method": "getConfiguration",
"data": {
...
"profiles": []
...
}
}5. Add a profile containing a cross line to the current configuration with the boundaries described by the configuration capabilities.
http://myserver/axis-cgi/radar/control.cgi{
"apiVersion": "2.1",
"context": "<client context>",
"method": "setConfiguration",
"params": {
...
"profiles": [
{
"name": "Zone",
"uid": 1,
"channel": 1,
"filters": [...],
"triggers": [
{
"type": "crossLine",
"alarmDirection": "leftToRight",
"data": [
[-1.0, 0.0],
[ 1.0, 0.0]
]
}
]
}
]
...
}
}6. Parse the response, which will contain an empty data object if the request is successful. This example shows what happens when the configuration is successfully set with the added crossline now in place, which will generate an alarm if an object crosses from left to right.
{
"apiVersion": "2.1",
"context": "<client context>",
"method": "setConfiguration",
"data": {}
}4. Parse the JSON response. In this example, the client’s configuration was successfully set and a cross line is now in place.
API references
Adjust detection sensitivity
This example will show you how to adjust the detection sensitivity of the radar. This is useful in noisy environments as it will decrease the frequency of false alarms and can be used as a complement to zone specific and global filters that are configured by setConfiguration and setGlobalFilters.
1. Request the configuration capabilities of the API.
http://myserver/axis-cgi/radar/radaranalytics.cgi{
"apiVersion": "2.1",
"context": "<client context>",
"method": "getConfigurationCapabilities"
}2. Parse the response, which will contain the allowed detection sensitivity levels.
{
"apiVersion": "2.1",
"context": "<client context>",
"method": "getConfigurationCapabilities",
"data": {
...
"detectionSensitivity": {
"values": [
"low",
"medium",
"high"
],
"default": "medium"
},
...
}
}3. Apply a new valid detection sensitivity value according to the capabilities.
http://myserver/axis-cgi/radar/radaranalytics.cgi{
"apiVersion": "2.1",
"method": "setDetectionSensitivity",
"params": {
"sensitivity": "medium"
}
}4. Parse the response.
{
"apiVersion": "2.1",
"method": "setDetectionSensitivity",
"data": {}
}API references
Adjust frequency channel
This example will show you how to set up two security radars to different frequency channels to avoid interference between them.
1. Find the current frequency channel for the first radar detector.
http://myserver/axis-cgi/radar/radaranalytics.cgi{
"apiVersion": "2.1",
"context": "<client context>",
"method": "getFrequencyChannel",
"params": {
"channel": 1
}
}2. Parse the response to receive the current frequency channel.
{
"apiVersion": "2.1",
"context": "<client context>",
"method": "getFrequencyChannel",
"data": {
"automatic": false,
"value": 1,
}
}3. Find the current frequency channel for the second radar detector.
http://myserver/axis-cgi/radar/radaranalytics.cgi{
"apiVersion": "2.1",
"context": "<client context>",
"method": "getFrequencyChannel",
"params": {
"channel": 1
}
}4. Parse the response to retrieve the current frequency channel.
{
"apiVersion": "2.1",
"context": "<client context>",
"method": "getFrequencyChannel",
"data": {
"automatic": false,
"value": 1,
}
}5. Find the allowed values for the first radar detector.
http://myserver/axis-cgi/radar/radaranalytics.cgi{
"apiVersion": "2.1",
"context": "<client context>",
"method": "setConfigurationCapabilities",
}6. Parse the response to receive the currently supported frequency channels.
{
"apiVersion": "2.1",
"context": "<client context>",
"method": "getConfigurationCapabilities",
"data": {
...
"frequencyChannel": {
"minValue": 1,
"maxValue": 2,
"default": 1
},
...
}
}7. Set a new value for the first radar detector.
http://myserver/axis-cgi/radar/radaranalytics.cgi{
"apiVersion": "2.1",
"context": "<client context>",
"method": "setFrequencyChannel",
"params": {
"value": 2,
"channel": 1
}
}6. Parse the response to apply the chosen frequency channel.
{
"apiVersion": "2.1",
"context": "<client context>",
"method": "setFrequencyChannel",
"data": {}
}API references
Mounting height and tilt of radar
This example will show you how to, after mounting the radar the radar detector on different heights and tilt angles, inform the radar and update the analytical algorithm to the changes.
1. Find the currently configured mounting height.
http://myserver/axis-cgi/radar/radaranalytics.cgi{
"apiVersion": "2.1",
"context": "<client context>",
"method": "getMountingHeight",
"params": {
"channel": 1
}
}2. Parse the response to receive the current mounting height and allowed values (in meter).
{
"apiVersion": "2.1",
"context": "<client context>",
"method": "getMountingHeight",
"data": {
"value": 3.5,
}
}3. Set a new value for the mounting height.
http://myserver/axis-cgi/radar/radaranalytics.cgi{
"apiVersion": "2.1",
"context": "<client context>",
"method": "setMountingHeight",
"params": {
"value": 5.1,
"channel": 1
}
}4. Parse the response to apply the new mounting height.
{
"apiVersion": "2.1",
"context": "<client context>",
"method": "setMountingHeight",
"data": {}
}5. Find the currently configured mounting tilt angle.
http://myserver/axis-cgi/radar/radaranalytics.cgi{
"apiVersion": "2.1",
"context": "<client context>",
"method": "getMountingTilt",
"params": {
"channel": 1
}
}6. Parse the response to receive the current mounting tilt as well as if the current value comes from an automatic or manual measurement.
{
"apiVersion": "2.1",
"context": "<client context>",
"method": "getMountingTilt",
"data": {
"automatic": false,
"value": 0
}
}7. Set a new value for the mounting tilt angle.
http://myserver/axis-cgi/radar/radaranalytics.cgiThe value of the field automatic will tell the application whether the measurement comes from an automatic source, such as an inclinometer, or a manual value. This is defined by the value object.
{
"apiVersion": "2.1",
"context": "<client context>",
"method": "setMountingTilt",
"params": {
"automatic": false,
"value": 10,
"channel": 1
}
}8. Parse the response to apply the new mounting tilt.
{
"apiVersion": "2.1",
"context": "<client context>",
"method": "setMountingTilt",
"data": {}
}API references
Get status of radar data
This example will show you how to test if the security radar is working correctly.
1. Get the current radar data reception status.
http://myserver/axis-cgi/radar/radaranalytics.cgi{
"apiVersion": "2.1",
"context": "<client context>",
"method": "getRadarDataStatus"
}2. Parse the response to receive the current status as a boolean, where true signifies normal operation.
{
"apiVersion": "2.1",
"context": "<client context>",
"method": "getRadarDataStatus",
"data": {
"value": true
}
}API references
Enable the swaying object filter
This example will show you how to reduce the number of false alarms from swaying objects such as trees or bushes. Unlike zone-specific filters that can be configured with setConfiguration, the swaying object filter is a global filter that requires a different setup.
1. Get the current configuration of the swaying object filter.
http://myserver/axis-cgi/radar/radaranalytics.cgi{
"apiVersion": "2.1",
"context": "<client context>",
"method": "getGlobalFilters",
"params": {
"channel": 1
}
}2. Parse the response to receive a list containing available global filters and their respective status.
{
"apiVersion": "2.1",
"context": "<client context>",
"method": "getGlobalFilters",
"data": {
"filters": [
{
"type": "swayingObjectFilter",
"active": false
}
]
}
}3. Enable the swaying objects filter.
http://myserver/axis-cgi/radar/radaranalytics.cgi{
"apiVersion": "2.1",
"context": "<client context>",
"method": "setGlobalFilters",
"params": {
"channel": 1,
"filters": [
{
"type": "swayingObjectFilter",
"active": true
}
]
}
}4. Parse the response. The returning data object will be empty if the request was successful.
{
"apiVersion": "2.1",
"context": "<client context>",
"method": "setGlobalFilters",
"data": {}
}API references
Determine support for automatic mounting tilt measurement
This example will show you how to check if your device supports automatic mounting tilt measurement or if the numbers needs to be added manually.
1. Request the configuration capabilities of the application
http://myserver/axis-cgi/radar/radaranalytics.cgi{
"apiVersion": "2.1",
"context": "<client context>",
"method": "getConfigurationCapabilities"
}2. Parse the response. The value of data.mountingTilt.automatic will determine if your device supports automatic tilt measurement.
{
"apiVersion": "2.1",
"method": "getConfigurationCapabilities",
"data": {
"coexistence": {
"maxNeighboringRadars": {
"values": [
1,
5
],
"default": 1
},
"group": {
"values": [
1,
2
],
"default": 1
}
},
"mountingHeight": {
"default": 3.5,
"maxValue": 100,
"minValue": 0.3
},
"mountingTilt": {
"automatic": true,
"default": 0,
"maxValue": 100,
"minValue": -100
}
}
}API references
Determine if the radar has been enabled
This example will show you how to check if the radar is enabled.
1. Request the current status of the radar.
http://myserver/axis-cgi/radar/control.cgi{
"apiVersion": "2.1",
"context": "<client context>",
"method": "getEnabled"
}2. Parse the response, where the object data.enabled will specify whether the radar is enabled.
{
"apiVersion": "2.1",
"context": "<client context>",
"method": "getEnabled"
"data": {
"enabled": true
}
}API references
Turn off the radar
This example will show you how to temporarily turn off the radar.
1. Request that the radar is turned off.
http://myserver/axis-cgi/radar/control.cgi{
"apiVersion": "2.1",
"context": "<client context>",
"method": "setEnabled",
"params": {
"enabled": false
}
}2. Parse the response, which will contain an empty data object if the request was successful.
{
"apiVersion": "2.1",
"context": "<client context>",
"method": "setEnabled"
"data": {}
}API references
Set coexistence group
This example will show you how to install four to six radar detectors within the range of each other and how to make sure that they don’t interfere with each other.
1. Find the maximum number of neighboring radars and coexistence groups.
http://myserver/axis-cgi/radar/radaranalytics.cgi{
"apiVersion": "2.1",
"context": "<client context>",
"method": "getConfigurationCapabilities"
}2. Parse the response. This will return the currently supported maximum number of neighbors and coexistence groups, which in this example means a number of neighbors between 1 and 5, and coexistence groups 1 and 2.
{
"apiVersion": "2.1",
"context": "<client context>",
"method": "getConfigurationCapabilities",
"data": {
...
"coexistence": {
"maxNeighboringRadars": {
"values": [
1,
5
],
"default": 1
},
"group": {
"values": [
1,
2
],
"default": 1
}
},
...
}
}3. Find the current number of neighbors and the coexistence group.
http://myserver/axis-cgi/radar/radaranalytics.cgi{
"apiVersion": "2.1",
"context": "<client context>",
"method": "getCoexistence"
}4. Parse the response. This will return the current value of the maximum number of neighbors and coexistence group, which in this example is 2 and 1 by default.
{
"apiVersion": "2.1",
"context": "<client context>",
"method": "getCoexistence",
"data": {
"maxNeighboringRadars": {
"value": 2
},
"group": {
"value": 1
}
}
}5. Set the maximum number of neighboring radars to the new value. The current radar should be set to one of the groups if the number of detectors are higher than 3.
http://myserver/axis-cgi/radar/radaranalytics.cgi{
"apiVersion": "2.1",
"context": "<client context>",
"method": "setCoexistence",
"params": {
"maxNeighboringRadars": 4,
"group": 2
}
}6. Parse the reponse, which will contain an empty data response if the request is successful.
{
"apiVersion": "2.1",
"context": "<client context>",
"method": "setCoexistence",
"data": {}
}API references:
Control API
getConfiguration
This method should be used when you want request the current radar event configuration.
Request
http://<servername>/axis-cgi/radar/control.cgi- Security level
Administrator
- Method
POST
{
"apiVersion": "2.1",
"context": "<client context>",
"method": "getConfiguration"
}| Parameter | Description |
apiVersion=<string> | The API version that should be used. |
context=<string> | The user sets this value and the application echoes it back in the response (optional). |
method="getConfiguration" | The method that should be used. |
Return value - Success
Returns the current event configuration as a JSON response. The values x and y represents numbers.
For a complete description of each field in the configuration, see Parameter description.
- HTTP Code
200 OK- Content-Type
application/json
{
"apiVersion": "2.1",
"context": "<client context>",
"method": "getConfiguration",
"data": {
"channels": [
{
"active": true,
"id": 1
}
],
"profiles": [
{
"name": "Zone 1",
"uid": 1,
"channel": 1,
"filters": [
{
"type": "objectType",
"small": false,
"human": true,
"vehicle": true,
"unknown": true,
"active": false
},
{
"type": "timeShortLivedLimit",
"data": 2,
"active": true
},
{
"type": "excludeArea",
"data": [[x,y], ..., [x,y]]
},
{
"type": "excludeArea",
"data": [[x,y], ..., [x,y]]
}
],
"triggers": [
{
"type": "includeArea",
"data": [[x,y], ..., [x,y]]
}
]
},
{...},
{...},
{...}
],
"configurationStatus": 0
}
}Response if the radar supports multiple channels:
Channel specific properties are set with data.channels. Please note that each profile has its own individual settings and refers to a channel id with the data.profiles[j].channel property.
{
"apiVersion": "2.1",
"context": "<client context>",
"method": "getConfiguration",
"data": {
"channels": [
{"active": true, "id": 1},
{"active": false, "id": 2},
{"active": false, "id": 3},
{"active": false, "id": 4}
],
"profiles": [
{
"name": "Zone 1",
"uid": 1,
"channel": 1,
"filters": [
{
"type": "objectType",
"small": false,
"human": true,
"vehicle": true,
"unknownType": true,
"active": false
},
{
"type": "timeShortLivedLimit",
"data": 2,
"active": true
},
{
"type": "excludeArea",
"data": [[x,y], ..., [x,y]]
},
{
"type": "excludeArea",
"data": [[x,y], ..., [x,y]]
}
],
"triggers": [
{
"type": "includeArea",
"data": [[x,y], ..., [x,y]]
}
]
},
{
"name": "Zone 2",
"uid": 2,
"channel": 3,
"filters": [...],
"triggers": [...]
},
{...},
{...},
{...}
],
"configurationStatus": 0
}
}| Parameter | Description |
apiVersion=<string> | The API version that was used in the request |
context=<string> | The context set by the user in the request (optional). |
method="getConfiguration" | The requested method. |
Return value - Failure
- HTTP Code
200 OK- Content-Type
application/json
{
"apiVersion": "Major.Minor",
"context": <string>,
"method": "getConfiguration",
"error": {
"code": <integer error code>,
"message": <error message>
}
}| Parameter | Description |
apiVersion=<string> | The API version that was used in the request |
context=<string> | The context set by the user in the request (optional). |
method="getConfiguration" | The requested method. |
error.code=<integer error code> | The error code. |
error.message=<string> | The error message for the corresponding error code. |
Error codes
See General error codes for a complete list of potential errors.
setConfiguration
This method should be used when you want to apply a new event configuration.
Modify specific properties
The following examples will change the values of a JSON event configuration to make it perform a specific action. In these examples, i represents an index in the profile array.
Modify include area:
The profile’s include area consists of n connected straight lines that connects the points [[x0,y0], ..., xn,yn]], and can be modified by changing the property params.profiles[i].triggers to:
"triggers": [
...
{
"type": "includeArea",
"data": [[x0,y0], ..., [xn,yn]]
},
...
]Modify exclude areas:
The profile’s exclude area consists of n connected straight lines that connects the points [[x0,y0], ..., xn,yn]], and can be modified by changing the property params.profiles[i].filters to:
"filters": [
...
{
"type": "excludeArea",
"data": [[x0,y0], ..., [xn,yn]]
},
...
]Please note that the exclude area object should be removed when the exclude area is not in use.
Set short-lived object filter:
To change the short-lived object filter value to t seconds you should start by modifying the property params.profiles[i].filters to:
"filters": [
...
{
"type": "timeShortLivedLimit",
"data": t,
"active": true
},
...
]Set object type object filter:
In order to change the object type filter values to include only humans you should start by modifying params.profiles[i].filters to:
"filters": [
...
{
"type": "objectType",
"small": false,
"human": true,
"vehicle": false,
"unknown": false,
"active": true
},
...
]Request
http://<servername>/axis-cgi/radar/control.cgi- Security level
Administrator
- Method
POST
{
"apiVersion": "2.1",
"context": "<client context>",
"method": "setConfiguration",
"params": {
"channels": [
{
"active": true,
"id": 1
}
],
"profiles": [
{
"name": "Profile 1",
"uid": 1,
"channel": 1,
"filters":
[
{"type": "objectType", "small": "false, "human": true, "vehicle": true, "unknownType": true, "active": false},
{"type": "timeShortLivedLimit", "data": t, "active": true},
{"type": "excludeArea", "data": [[x,y], ..., [x,y]]},
{"type": "excludeArea", "data": [[x,y], ..., [x,y]]}
],
"triggers": [
{"type": "includeArea", "data": [[x,y], ..., [x,y]]}
],
},
{...},
{...},
{...}
]
}
}| Parameter | Type | Description |
apiVersion | String | The API version that should be used. |
context=<string> | String | The user sets this value and the application echoes it back in the response (optional). |
method="setConfiguration" | String | The method that should be used. |
params | JSON object | Container for a complete event configuration. To remove a profile, simply remove that profile object from the params.profiles array. For a complete description of each field in the configuration, see Parameter description. |
Return value - Success
- HTTP Code
200 OK- Content-Type
application/json
{
"apiVersion": "2.1",
"context": "<client context>",
"method": "setConfiguration",
"data": {}
}| Parameter | Type | Description |
apiVersion | String | The API version that was used in the request. |
context=<string> | String | The context set by the user in the request (optional). |
method="setConfiguration" | String | The requested method. |
data | JSON object | Empty when the request is successful. |
Return value - Failure
- HTTP Code
200 OK- Content-Type
application/json
{
"apiVersion": "Major.Minor",
"context": <string>,
"method": "setConfiguration",
"error": {
"code": <integer error code>,
"message": <error message>
}
}| Parameter | Description |
apiVersion=<string> | The API version that was used in the request |
context=<string> | The context set by the user in the request (optional). |
method="setConfiguration" | The requested method. |
error.code=<integer error code> | The error code. |
error.message=<string> | The error message for the corresponding error code. |
Error codes
See General error codes for a complete list of potential errors.
getConfigurationCapabilities
This method should be used when you want to request the boundaries and default API values.
Request
http://<servername>/axis-cgi/radar/control.cgi- Security level
Administrator
- Method
POST
{
"apiVersion": "2.1",
"context": "<client context>",
"method": "getConfigurationCapabilities"
}| Parameter | Description |
apiVersion=<string> | The API version that should be used. |
context=<string> | The user sets this value and the application echoes it back in the response (optional). |
method="getConfigurationCapabilities" | The method that should be used. |
Return value - Success
- HTTP Code
200 OK- Content-Type
application/json
{
"apiVersion": "2.1",
"context": "<client context>",
"method": "getConfigurationCapabilities",
"data":{
"filters": [
{
"type": "excludeArea",
"min": [-1.0, -1.0],
"max": [1.0, 1.0],
"minNbrVertices": 3,
"maxNbrVertices": ...,
"defaultInstance": [...]
},
{
"type": "timeShortLivedLimit", ...
"min": ...,
"max": ...,
"default": ...,
"defaultActive": ...
},
{
"type": "minimumSpeedLimit", ...
"min": ...,
"max": ...,
"default": ...,
"defaultActive": ...
},
{
"type": "maximumSpeedLimit", ...
"min": ...,
"max": ...,
"default": ...,
"defaultActive": ...
},
],
"triggers": [
{
"type": "crossLine",
"min": [-1.0, -1.0],
"max": [1.0, 1.0],
"minNbrVertices": 2,
"maxNbrVertices": ...,
"minNbrInstances": ...,
"maxNbrInstances": ...,
"validAlarmDirection": [...],
"defaultAlarmDirection": ...
}
],
"profiles": {
"minNbrProfilesPerChannel": ...,
"maxNbrProfilesPerChannel": ...,
"minLengthName": ...,
"maxLengthName": ...
}
}
}See Parameter description for a complete description of all parameters in the response.
Return value - Failure
- HTTP Code
200 OK- Content-Type
application/json
{
"apiVersion": "Major.Minor",
"context": <string>,
"method": "getConfigurationCapabilities",
"error": {
"code": <integer error code>,
"message": <error message>
}
}| Parameter | Description |
apiVersion=<string> | The API version that was used in the request |
context=<string> | The context set by the user in the request (optional). |
method="getConfigurationCapabilities" | The requested method. |
error.code=<integer error code> | The error code. |
error.message=<string> | The error message for the corresponding error code. |
Error codes
See General error codes for a complete list of potential errors.
getEnabled
This method should be used when you want to determine if the radar is currently enabled or disabled.
Request
http://<servername>/axis-cgi/radar/control.cgi- Security level
Administrator
- Method
POST
{
"apiVersion": "2.1",
"context": "<client context>",
"method": "getEnabled"
}| Parameter | Type | Description |
apiVersion | String | The API version that should be used. |
context=<string> | String | The user sets this value and the application echoes it back in the response (optional). |
method="getEnabled" | String | The method that should be used. |
Return value - Success
- HTTP code
200 OK- Content-type
application/json
{
"apiVersion": "2.1",
"context": "<client context>",
"method": "getEnabled",
"data": {
"enabled": <true|false>
}
}See Parameter description for a complete description of all parameters in the response.
Return value - Failure
- HTTP code
200 OK- Content-type
application/json
{
"apiVersion": "Major.Minor",
"context": <string>,
"method": "getEnabled",
"error": {
"code": <integer error code>,
"message": <error message>
}
}| Parameter | Description |
apiVersion=<string> | The API version that was used in the request |
context=<string> | The context set by the user in the request (optional). |
method="getEnabled" | The requested method. |
error.code=<integer error code> | The error code. |
error.message=<string> | The error message for the corresponding error code. |
Error codes
See General error codes for a complete list of potential errors.
setEnabled
This method should be used when you want to enable or disable the radar.
Request
http://<servername>/axis-cgi/radar/control.cgi- Security level
Administrator
- Method
POST
{
"apiVersion": "2.1",
"context": "<client context>",
"method": "setEnabled",
"params": {
"enabled": <true|false>
}
}| Parameter | Type | Description |
apiVersion | String | The API version that should be used. |
context | String | The user sets this value and the application echoes it back in the response (optional). |
method | String | The method that should be used. |
params.enabled=<true|false> | Boolean | Container for the method specific parameters that specifies if the radar should be enabled (true) or disabled (false). |
Return value - Success
- HTTP code
200 OK- Content-type
application/json
{
"apiVersion": "2.1",
"context": "<client context>",
"method": "setEnabled",
"data": {}
}See Parameter description for a complete description of all parameters in the response.
Return value - Failure
- HTTP code
200 OK- Content-type
application/json
{
"apiVersion": "Major.Minor",
"context": <client context>,
"method": "setEnabled",
"error": {
"code": <integer error code>,
"message": <error message>
}
}| Parameter | Description |
apiVersion=<string> | The API version that was used in the request |
context=<string> | The context set by the user in the request (optional). |
method="setEnabled" | The requested method. |
error.code=<integer error code> | The error code. |
error.message=<string> | The error message for the corresponding error code. |
Error codes
See General error codes for a complete list of potential errors.
getSupportedVersions
This method should be used when you want to create a list containing all supported API versions.
Request
http://<servername>/axis-cgi/radar/control.cgi- Security level
Administrator
- Method
POST
{
"context": "<client context>",
"method": "getSupportedVersions"
}| Parameter | Type | Description |
context=<string> | String | The user sets this value and the application echoes it back in the response (optional). |
method="getSupportedVersions" | String | The method that should be used. |
Return value - Success
- HTTP Code
200 OK- Content-Type
application/json
{
"apiVersion": "2.1",
"context": "<client context>",
"method": "getSupportedVersions",
"data":
{
"apiVersions": [
"<Major1>.<Minor1>",
"<Major2>.<Minor2>"
]
}
}See Parameter description for a complete description of all parameters in the response.
Return value - Failure
- HTTP Code
200 OK- Content-Type
application/json
{
"apiVersion": "Major.Minor",
"context": <client context>,
"method": "getSupportedVersions",
"error": {
"code": <integer error code>,
"message": <error message>
}
}| Parameter | Description |
apiVersion=<string> | The API version that was used in the request |
context=<string> | The context set by the user in the request (optional). |
method="getSupportedVersions" | The requested method. |
error.code=<integer error code> | The error code. |
error.message=<string> | The error message for the corresponding error code. |
Error codes
See General error codes for a complete list of potential errors.
sendAlarmEvent
This method should be used when you want to send a stateful alarm event for a specific uid profile. Stateful alarm events are active for a few seconds, and the response message will be returned immediately. This is useful when you want to check if a configuration has been correctly set (e.g. it starts the recording) as all profile-related events will be sent.
Profile events will be sent regardless of their current state.
Request
http://<servername>/axis-cgi/radar/control.cgi- Security level
Operator
- Method
POST
{
"apiVersion": "2.1",
"context": "<client context>",
"method": "sendAlarmEvent",
"params": {
"profile": <uid>
}
}| Parameter | Type | Description |
apiVersion | String | The API version that should be used. |
context=<string> | String | The user sets this value and the application echoes it back in the response (optional). |
method=<sendAlarmEvent> | String | The method that should be used. |
data.profile=<uid> | JSON object | Specifies the profile that should raise an alarm. |
Return value - Success
- HTTP Code
200 OK- Content-Type
text/json
{
"apiVersion": "2.1",
"context": "<client context>",
"method": "sendAlarmEvent",
"data" {}
}See Parameter description for a complete description of all parameters in the response.
Return value - Failure
- HTTP Code
200 OK- Content-Type
application/json
{
"apiVersion": "Major.Minor",
"context": <string>,
"method": "sendAlarmEvent",
"error": {
"code": <integer error code>,
"message": <error message>
}
}| Parameter | Description |
apiVersion=<string> | The API version that was used in the request |
context=<string> | The context set by the user in the request (optional). |
method="sendAlarmEvent" | The requested method. |
error.code=<integer error code> | The error code. |
error.message=<string> | The error message for the corresponding error code. |
Error codes
See General error codes for a complete list of potential errors.
Parameter description
The structure of a configuration object is the same for both the data object in the response for getConfiguration and the params object requested when using setConfiguration. This is true for both single and multichannel products, where the channels objects will mirror the different VAPIX channel properties.
Example configuration
The following example configuration will be further described in Parameter description table
{
"channels": [
{
"active": bool,
"id": 1
}
],
"profiles": [
{
"name": "<client nice-name>",
"uid": <uid>,
"channel": 1,
"filters": [
{"type": "objectType", "small": false, "human": true, "vehicle": true, "unknown": true, "active": false},
{"type": "timeShortLivedLimit", "data": 2, "active": true},
{"type": "excludeArea", "data": [[x,y], ..., [x,y]]},
{"type": "excludeArea", "data": [[x,y], ..., [x,y]]}
],
"triggers": [
{"type": "includeArea", "data": [[x,y], ..., [x,y]]}
]
},
{...},
{...},
{...}
],
"configurationStatus": 0
}Parameter description table
All parameters and properties are mandatory unless otherwise specified. Please note that exclusion filters are optional.
The channels object contains general information for all profiles using that channel.
| Property | Type | Default value | Valid values | Description |
channels[i].active | Boolean | true | true, false | Active profiles for the channel are set to true. Inactive profiles are set to false. |
channels[i].id | Integer | 1 | 1, ..., #channels | The channel value applied when requesting a video by using media.amp. Note that it starts at 1. |
The profiles object contains information for each individual profile.
| Property | Type | Default value | Valid value | Description |
profiles[j].name | String | “Profile <uid>” | <string> | A unicode string found in the nice name of the event, and visible to the end user in the action rule list. |
profiles[j].channel | Integer | 1 | 1, 2, 3, ..., | Should match the id of the corresponding channel in channels. |
profiles[j].uid | Integer | 1 | 1, 2, 3, ..., | A unique profile id. |
profiles[j].filters | Array | An array of exclusion filters. | ||
profiles[j].triggers | Array | An array of triggers. |
All exclusion filters from profiles[j].filters have a similar structure and are all optional. A filter not present in the profiles[].filters array during the configuration will be created with the default values specified in getConfigurationCapabilities.
The properties of the objectType filter each represent a certain type of object. For example, setting vehicle to false will let vehicles enter the alarm area without triggering an event. The object type small include small animals such as rodents, small dogs and birds, while unknown includes everything not applicable by the other types.
| Property | Type | Valid values | Description |
profiles[j].filters[k].type | String | objectType | Specifies the exclusion filter type. |
profiles[j].filters[k].active | Boolean | true, false | Specifies if the filter is active. |
profiles[j].filters[k].small | Boolean | true, false | Specifies if small objects should generate events. Default value is true. |
profiles[j].filters[k].human | Boolean | true, false | Specifies if humans should generate events. Default value is true. |
profiles[j].filters[k].vehicle | Boolean | true, false | Specifies if vehicles should generate events. Default value is true. |
profiles[j].filters[k].unknown | Boolean | true, false | Specifies if unknown objects should generate events. Default value is true. |
The timeShortLivedLimit filter reflects the number of seconds an object is tracked before raising an alarm. The alarm will be temporarily suppressed If the object does something that could trigger an alarm before the set time has passed, but if the object is still tracked after the set time has expired, the alarm will be raised. Should the object disappear from the radar view before the set time expires, the alarm will not be raised.
| Property | Type | Valid values | Description |
profiles[j].filters[k].type | String | timeShortLivedLimit | Specifies the type of exclusion filter. |
profiles[j].filters[k].active | Boolean | true, false | Specifies if the filter is active. |
profiles[j].filters[k].data | Integer | 1, ..., | Seconds alive before generating an event. |
The excludeArea filter specifies an exclude area where objects doesn’t generate any events. An exclude area is made out of an array of points [[x0,y0], ..., [xn,yn]], and the coordinates are normalized to the size of the image so that the visible view spans from -1 to 1 in both the horizontal and vertical direction.
| Property | Type | Valid values | Description |
profiles[j].filters[k].type | String | excludeArea | Specifies the type of exclusion filter. |
profiles[j].triggers[k].data | [[x0,y0], ..., [xn,yn]] | - 1, ..., 1 | The exclude area polygon. |
The minimumSpeedLimit filter specifies the minimum speed that an object must travel at to generate an event.
| Property | Type | Valid values | Description |
profiles[j].filters[k].type | String | minimumSpeedLimit | Specifies the exclusion filter type. |
profiles[j].filters[k].active | Boolean | true, false | Specifies if the filter is active. |
profiles[j].filters[k].data | Float | 0, ...,(1) | The minimum speed in meters per second. |
- Maximum valid value can be obtained from
getConfigurationCapabilities
The maximumSpeedLimit filter specifies the maximum speed that an object must travel at to generate an event.
| Property | Type | Valid values | Description |
profiles[j].filters[k].type | String | maximumSpeedLimit | Specifies the exclusion filter type. |
profiles[j].filters[k].active | Boolean | true, false | Specifies if the filter is active. |
profiles[j].filters[k].data | Float | 0, ...,(1) | The maximum speed in meters per seconds. |
The only trigger types are crossLine and includeArea, which means that the array profiles[j].triggers should contain no more than one cross line or one include area.
| Property | Type | Valid values | Description |
profiles[j].triggers[0].type | String | crossLine | Specifies that the trigger is a cross line. |
profiles[j].triggers[0].alarmDirection | String | leftToRight rightToLeft | Specifies the direction in which an object must cross the cross line to generate an event. |
profiles[j].triggers[0].data | [[x0,y0], ..., [xn,yn]] | -1, ..., 1 | A cross line is described as an array of points [[x0, y0], ..., [xn, yn]] and the unit are normalized to the size of the image so that the visible view spans from -1 to 1 in both the horizontal and vertical direction. |
| Property | Type | Valid values | Description |
profiles[j].triggers[0].type | String | includeArea | Specifies that it is an include area. |
profiles[j].triggers[0].data | [[x0, y0], ..., [xn, yn]] | -1, ..., 1 | An include area is described as an array of points [[x0, y0], ..., [xn, yn]] and the unit are normalized to the size of the image, so that the visible view spans from -1 to 1 in both the horizontal and vertical direction. |
| Property | Type | Description |
configurationStatus | Integer | This property is read-only and ignored by setConfiguration. The initial value is 0, which indicates a default configuration where no configuration has been set. Each time a configuration is set, the value is increased by 1 up to the maximum number of 2 147 483 647, after which the value will be reset to 1. |
Configuration capabilities parameter description
The following tables will describe the parameters found in getConfigurationCapabilities.
Filters
| Property | Type | Description |
min | [int, int] | An array [xPos, yPos] specifying the minimum allowed values in the x- and y-direction for the area. |
max | [int, int] | An array [xPos, yPos] specifying the maximum allowed values in the x- and y- direction for the area. |
minNbrVertices | Integer | The minimum number of vertices the area may contain. |
maxNbrVertices | Integer | The maximum number of vertices the area may contain. |
defaultInstance | [ [ x,y], ..., [x,y ] ] | The default exclude area contains an array of arrays that specifies the default vertices. |
| Property | Type | Description |
default | List of strings | The default object types that will generate an alarm when the filter is active. The strings in this array correspond to the keys of the objectType filter configuration object found in Parameter description table. |
defaultActive | Boolean | Specifies if the filter is active by default. |
| Property | Type | Description |
min | int | The minimum allowed time in seconds. |
max | int | The maximum allowed time in seconds. |
default | int | The default time in seconds. |
defaultActive | Boolean | Specifies if the filter is active by default. |
| Property | Type | Description |
min | Float | The minimum allowed speed in meters per second. |
max | Float | The maximum allowed speed in meters per second. |
default | Float | The default speed in meters per second. |
defaultActive | Boolean | Specifies if the filter is active by default. |
| Property | Type | Description |
min | Float | The minimum allowed speed in meters per second. |
max | Float | The maximum allowed speed in meters per second. |
default | Float | The default speed in meters per second. |
defaultActive | Boolean | Specifies if the filter is active by default. |
Triggers
| Property | Type | Description |
min | [int, int] | An array [xPos, yPos] with the minimum allowed values in the x- and y-direction for the cross line. |
max | [int, int] | An array [xPos, yPos] with the maximum allowed values in the x- and y-direction for the cross line. |
minNbrVertices | int | The minimum number of vertices the cross line may contain. |
maxNbrVertices | int | The maximum number of vertices the cross line may contain. |
minNbrInstances | int | The minimum allowed number of cross lines. |
maxNbrInstances | int | The maximum allowed number of cross lines. |
validAlarmDirections | List of strings | The possible directions that the cross line can have. |
defaultInstance | [[x, y], ..., [x, y]] | The default cross line containing an array of arrays specifying the default vertices. |
defaultAlarmDirection | String | The default alarm direction for a cross line. |
| Property | Type | Description |
min | [int, int] | An array [xPos, yPos] with the minimum allowed values in the x- and y-direction for the area. |
max | [int, int] | An array [xPos, yPos] with the maximum allowed values in the x- and y-direction for the area. |
minNbrVertices | int | The minimum number of angles the area may contain. |
maxNbrVertices | int | The maximum number of angles the area may contain. |
minNbrInstances | int | The minimum allowed number of areas. |
maxNbrInstances | int | The maximum allowed number of areas. |
defaultInstance | [[x, y], ..., [x, y]] | The default include area containing an array of arrays specifying the default angles. |
Profiles
| Property | Type | Description |
minNbrProfilesPerChannel | int | The minimum number of profiles a configuration may contain. |
maxNbrProfilesPerChannel | int | The maximum number of profiles a configuration may contain. |
minLengthName | int | The minimum number of characters for a profile name. |
maxLengthName | int | The maximum number of characters for a profile name. |
General error codes
This table lists the general errors that can occur for any method in the Control API.
| Code | Description |
1000 | Internal error. |
2000 | The requested API version is not supported by this implementation. |
2001 | The format of a provided JSON parameter was incorrect. |
2002 | Conflicting input parameters, e.g. two profiles with the same uid. |
2003 | A mandatory input parameter was not found in the input. |
2004 | An input parameter has an incorrect type. |
2005 | An unexpected parameter was passed. |
8000 | The requested method is not supported by this implementation. |
8003 | The provided input was not well-formed JSON. |
Analytics API
getConfigurationCapabilities
This method should be used when you want to request capabilities information from the Analytics API.
Request
http://<servername>/axis-cgi/radar/radaranalytics.cgi- Security level
Administrator
- Method
POST
{
"apiVersion": "2.1",
"context": "<client context>",
"method": "getConfigurationCapabilities"
}| Parameter | Description |
apiVersion=<string> | The API version that should be used. |
context=<string> | The user sets this value and the application echoes it back in the response (optional). |
method="getConfigurationCapabilities" | The method that should be used. |
Return value - Success
- HTTP code
200 OK- Content-type
application/json
{
"apiVersion": "2.1",
"context": "<client context>",
"method": "getConfigurationCapabilities",
"data": {
"coexistence": {
"maxNeighboringRadars": {
"values": [<integer>, ...],
"default": <integer>
},
"group": {
"values": [<integer>, ...],
"default": <integer>
}
},
"frequencyChannel": {
"automatic": <true|false>,
"values": [<integer|string>, ...],
"default": <integer|string>
},
"mountingHeight": {
"minValue": <number>,
"maxValue": <number>,
"default": <number>
},
"mountingTilt": {
"minValue": <number>,
"maxValue": <number>,
"automatic": <true|false>,
"default": <number>
}
}
}| Parameter | Description |
apiVersion=<string> | The API version that was used in the request |
context=<string> | The context set by the user in the request (optional). |
method="getConfigurationCapabilities" | The requested method. |
data.coexistence.maxNeighboringRadars.default=<integer> | Present only if the device supports coexistence. The default value of the coexistence mode. |
data.coexistence.maxNeighboringRadars.values=<integer> | Present only if the device supports coexistence. The allowed values of the coexistence mode. |
data.coexistence.group.default=<integer> | Present only if the device supports coexistence. The default value of the coexistence group. |
data.coexistence.group.values=<integer> | Present only if the device supports coexistence. The allowed values of the coexistence group. |
data.frequencyChannel.automatic=<true|false> | Present only if the device supports multiple frequency channels. Indicates whether the device supports automatic frequency channel selection. Can be either true or false. |
data.frequencyChannel.default=<integer> | The default value of the frequency channel. |
data.frequencyChannel.values=<integer|string> | The allowed values for the frequency channel. |
data.mountingHeight.default=<number> | The default value of the mounting height. |
data.mountingHeight.minValue=<number> | The smallest allowed mounting height value. |
data.mountingHeight.maxValue=<number> | The largest allowed mounting height value. |
data.mountingTilt.automatic=<boolean> | Indicates whether the device supports automatic mounting tilt measurement. Can be either true or false. |
data.mountingTilt.default=<number> | The default value of the mounting tilt angle. |
data.mountingTilt.minValue=<number> | The smallest allowed mounting tilt angle value. |
data.mountingTilt.maxValue=<number> | The largest allowed mounting tilt angle value. |
Return value - Failure
- HTTP code
200 OK- Content-type
application/json
{
"apiVersion": "Major.Minor",
"context": "<client context>",
"method": "getConfigurationCapabilities",
"error": {
"code": <integer error code>,
"message": <string>
}
}| Parameter | Description |
apiVersion=<string> | The API version that was used in the request |
context=<string> | The context set by the user in the request (optional). |
method="getConfigurationCapabilities" | The requested method. |
error.code=<integer error code> | The error code. |
error.message=<string> | The error message for the corresponding error code. |
Error codes
See General error codes for a complete list of potential errors.
setDetectionSensitivity
This method should be used when you want to set the detection sensitivity of the radar. A higher detection sensitivity increases the detection probability, but could also lead to more false alarms.
Request
http://myserver/axis-cgi/radar/radaranalytics.cgi- Security level
Operator
- Method
POST
{
"apiVersion": "2.1",
"context": "<client context>",
"method": "setDetectionSensitivity",
"params": {
"value": <string>
}
}| Parameter | Description |
apiVersion=<string> | The API version that should be used. |
context=<string> | The user sets this value and the application echoes it back in the response (optional). |
method="setDetectionSensitivity" | The method that should be used. |
params.value=<string> | The detection sensitivity that should be used. Allowed values are provided by getConfigurationCapabilities. |
Return value - Success
- HTTP Code
200 OK- Content-Type
application/json
{
"apiVersion": "2.1",
"context": "<client context>",
"method": "setDetectionSensitivity",
"data": {}
}| Parameter | Description |
apiVersion=<string> | The API version that was used in the request |
context=<string> | The context set by the user in the request (optional). |
method="setDetectionSensitivity" | The requested method. |
data | Empty when the request is successful. |
Return value - Failure
- HTTP Code
200 OK- Content-Type
application/json
{
"apiVersion": "2.1",
"context": "<client context>",
"method": "setDetectionSensitivity",
"error": {
"code": <integer error code>,
"message": <string>
}
}| Parameter | Description |
apiVersion=<string> | The API version that was used in the request |
context=<string> | The context set by the user in the request (optional). |
method="setDetectionSensitivity" | The requested method. |
error.code=<integer error code> | The error code. |
error.message=<string> | The error message for the corresponding error code. |
Error codes
See General error codes for a complete list of potential errors.
getDetectionSensitivity
This method should be used when you want to check the current detection sensitivity of the radar.
Request
http://myserver/axis-cgi/radar/radaranalytics.cgi- Security level
Operator
- Method
POST
{
"apiVersion": "2.1",
"context": "<client context>",
"method": "getDetectionSensitivity",
"data": {
"value": "high",
"allowedValues": [
"low",
"medium",
"high"
]
}
}| Parameter | Description |
apiVersion=<string> | The API version that should be used. |
context=<string> | The user sets this value and the application echoes it back in the response (optional). |
method="getDetectionSensitivity" | The method that should be used. |
Return value - Success
- HTTP Code
200 OK- Content-Type
application/json
{
"apiVersion": "2.1",
"context": "<client context>",
"method": "getDetectionSensitivity",
"data": {
"value": "high",
}
}| Parameter | Description |
apiVersion=<string> | The API version that was used in the request |
context=<string> | The context set by the user in the request (optional). |
method="getDetectionSensitivity" | The requested method. |
data.value=<string> | The current detection sensitivity. |
Return value - Failure
- HTTP Code
200 OK- Content-Type
application/json
{
"apiVersion": "2.1",
"context": "<client context>",
"method": "getDetectionSensitivity",
"error": {
"code": <integer error code>,
"message": <string>
}
}| Parameter | Description |
apiVersion=<string> | The API version that was used in the request |
context=<string> | The context set by the user in the request (optional). |
method="getDetectionSensitivity" | The requested method. |
error.code=<integer error code> | The error code. |
error.message=<string> | The error message for the corresponding error code. |
Error codes
See General error codes for a complete list of potential errors.
setCoexistence
This method should be used when you want to set the coexistence mode of the radar. In cases where multiple radar detectors are within each others’ active area, you need to set an appropriate coexistence mode that will reduce the risk of the radar detectors interfering with each other.
This method is only available if the coexistence key is present in the response retrieved from getConfigurationCapabilities.
Request
http://myserver/axis-cgi/radar/radaranalytics.cgi- Security level
Operator
- Method
POST
{
"apiVersion": "2.1",
"context": "<client context>",
"method": "setCoexistence",
"params": {
"maxNeighboringRadars": <maximum number of neighboring radars>,
"channel": <radar channel>,
"group": <coexistence group>
}
}| Parameter | Description |
apiVersion=<string> | The API version that should be used. |
context=<string> | The user sets this value and the application echoes it back in the response (optional). |
method="setCoexistence" | The method that should be used. |
params.maxNeighboringRadars=<integer> | The maximum number of neighboring radars. |
params.channel=<integer> | Specifies on which radar channel the coexistence mode should be set (optional). All radar channels will have their frequency channel set to params.value if this parameter is omitted. |
params.group=<integer> | Specifies the group a radar belong to (optional). This parameter is optional if the maximum number of neighboring radars are 2 or fewer. The radar will belong to group 1 if this parameter is omitted. |
Return value - Success
- HTTP Code
200 OK- Content-Type
application/json
{
"apiVersion": "2.1",
"context": "<client context>",
"method": "setCoexistence",
"data": {}
}| Parameter | Description |
apiVersion=<string> | The API version that was used in the request |
context=<string> | The context set by the user in the request (optional). |
method="setCoexistence" | The requested method. |
data | Empty when the request is successful. |
Return value - Failure
- HTTP Code
200 OK- Content-Type
application/json
{
"apiVersion": "2.1",
"context": "<client context>",
"method": "setCoexistence",
"error": {
"code": <integer error code>,
"message": <string>
}
}| Parameter | Description |
apiVersion=<string> | The API version that was used in the request |
context=<string> | The context set by the user in the request (optional). |
method="setCoexistence" | The requested method. |
error.code=<integer error code> | The error code. |
error.message=<string> | The error message for the corresponding error code. |
Error codes
See General error codes for a complete list of potential errors.
getCoexistence
This method should be used when you want to check the current coexistence mode of the radar sensor.
This method is only available if the coexistence key is present in the response retrieved from getConfigurationCapabilities.
Request
http://myserver/axis-cgi/radar/radaranalytics.cgi- Security level
Operator
- Method
POST
{
"apiVersion": "2.1",
"context": "<client context>",
"method": "getCoexistence",
"params": {
"channel": <radar channel>,
}
}| Parameter | Description |
apiVersion=<string> | The API version that should be used. |
context=<string> | The user sets this value and the application echoes it back in the response (optional). |
method="getCoexistence" | The method that should be used. |
params.channel=<integer> | Specifies the radar channel whose coexistence mode should be returned in the response. The coexistence mode for radar channel 1 will be returned if this parameter is omitted. |
Return value - Success
- HTTP Code
200 OK- Content-Type
application/json
{
"apiVersion": "2.1",
"context": "<client context>",
"method": "getCoexistence",
"maxNeighboringRadars": {
"value": 1
}
}| Parameter | Description |
apiVersion=<string> | The API version that was used in the request |
context=<string> | The context set by the user in the request (optional). |
method="getCoexistence" | The requested method. |
data.maxNeighboringRadars | The maximum number of neighboring radars. |
Return value - Failure
- HTTP Code
200 OK- Content-Type
application/json
{
"apiVersion": "2.1",
"context": "<client context>",
"method": "getCoexistence",
"error": {
"code": <integer error code>,
"message": <string>
}
}| Parameter | Description |
apiVersion=<string> | The API version that was used in the request |
context=<string> | The context set by the user in the request (optional). |
method="getCoexistence" | The requested method. |
error.code=<integer error code> | The error code. |
error.message=<string> | The error message for the corresponding error code. |
Error codes
See General error codes for a complete list of potential errors.
setFrequencyChannel
This method should be used when you want to set the frequency channel used by the radar sensor. Setting two radar detectors that are within each others’ active area to different frequency channels will remove the risk of interference.
This method is only available if a frequencyChannel key is present in the response retrieved from getConfigurationCapabilities.
Request
http://myserver/axis-cgi/radar/radaranalytics.cgi- Security level
Operator
- Method
POST
{
"apiVersion": "2.1",
"context": "<client context>",
"method": "setFrequencyChannel",
"params": {
"automatic": <true|false>,
"value": <frequency channel>,
"channel": <radar channel>
}
}| Parameter | Description |
apiVersion=<string> | The API version that should be used. |
context=<string> | The user sets this value and the application echoes it back in the response (optional). |
method="setFrequencyChannel" | The method that should be used. |
params.automatic=<true|false> | Indicates if the automatic frequency channel selection should be used (optional). This can only be true if the device supports this functionality, otherwise an error will be returned. Whether your device supports this functionality can be queried by checking the field frequencyChannel.automatic in the response from getConfigurationCapabilities. |
params.value=<integer|string> | Specifies the frequency channel that should be used. Allowed values are provided by getConfigurationCapabilities |
params.channel=<integer> | Specifies which radar channel whose frequency channel should be set (optional). All radar channels will have their frequency channel st to params.value if this parameter is omitted. |
Return value - Success
- HTTP Code
200 OK- Content-Type
application/json
{
"apiVersion": "2.1",
"context": "<client context>",
"method": "setFrequencyChannel",
"data": {}
}| Parameter | Description |
apiVersion=<string> | The API version that was used in the request |
context=<string> | The context set by the user in the request (optional). |
method="setFrequencyChannel" | The requested method. |
data | Empty when the request is successful. |
Return value - Failure
- HTTP Code
200 OK- Content-Type
application/json
{
"apiVersion": "2.1",
"context": "<client context>",
"method": "setFrequencyChannel",
"error": {
"code": <integer error code>,
"message": <string>
}
}| Parameter | Description |
apiVersion=<string> | The API version that was used in the request |
context=<string> | The context set by the user in the request (optional). |
method="setFrequencyChannel" | The requested method. |
error.code=<integer error code> | The error code. |
error.message=<string> | The error message for the corresponding error code. |
Error codes
See General error codes for a complete list of potential errors.
getFrequencyChannel
This method should be used when you want to check the current frequency channel on the radar sensor.
This method is only available if the frequencyChannel key is present in the response retrieved from getConfigurationCapabilities.
Request
http://myserver/axis-cgi/radar/radaranalytics.cgi- Security level
Operator
- Method
POST
{
"apiVersion": "2.1",
"context": "<client context>",
"method": "getFrequencyChannel",
"params": {
"channel": <radar channel>
}
}| Parameter | Description |
apiVersion=<string> | The API version that should be used. |
context=<string> | The user sets this value and the application echoes it back in the response (optional). |
method="getFrequencyChannel" | The method that should be used. |
params.channel=<integer> | Specifies the radar channel whose frequency channel should be returned in the response (optional). The frequency channel for radar channel 1 will be returned if this parameter is omitted. |
Return value - Success
- HTTP Code
200 OK- Content-Type
application/json
{
"apiVersion": "2.1",
"context": "<client context>",
"method": "getFrequencyChannel",
"data": {
"automatic": <true|false>,
"value": 1,
}
}| Parameter | Description |
apiVersion=<string> | The API version that was used in the request |
context=<string> | The context set by the user in the request (optional). |
method="getFrequencyChannel" | The requested method. |
data.automatic=<true|false> | Indicates if the device is configured to select frequency channels automatically. |
data.value=<integer|string> | The current frequency channel for the requested radar channel. |
Return value - Failure
- HTTP Code
200 OK- Content-Type
application/json
{
"apiVersion": "Major.Minor",
"context": "<client context>",
"method": "getFrequencyChannel",
"error": {
"code": <integer error code>,
"message": <string>
}
}| Parameter | Description |
apiVersion=<string> | The API version that was used in the request |
context=<string> | The context set by the user in the request (optional). |
method="getFrequencyChannel" | The requested method. |
error.code=<integer error code> | The error code. |
error.message=<string> | The error message for the corresponding error code. |
Error codes
See General error codes for a complete list of potential errors.
setGlobalFilters
This method should be used when you want to apply the global filter configurations on the radar.
Enable a global filter:
In order to enable a global filter, the params.filters should first be modified:
"filters": [
...
{
"type": "<FilterName>",
"active": true
},
...
]<FilterName> should be replaced with the name of one of the supported filters obtained by using the method getGlobalFilters.
Request
http://<servername>/axis-cgi/radar/radaranalytics.cgi- Security level
Administrator
- Method
POST
{
"apiVersion": "2.1",
"context": "<client context>",
"method": "setGlobalFilters",
"params": {
"filters": [
{
"type": "swayingObjectFilter",
"active": true
}
]
}
}| Parameter | Description |
apiVersion=<string> | The API version that should be used. |
context=<string> | The user sets this value and the application echoes it back in the response (optional). |
method="setGlobalFilters" | The method that should be used. |
params.filters=<list of objects> | Specifies the configuration for the filter.name and status of filter.active. |
Return value - Success
- HTTP Code
200 OK- Content-Type
application/json
{
"apiVersion": "2.1",
"context": "<client context>",
"method": "setGlobalFilters",
"data": {}
}| Parameter | Description |
apiVersion=<string> | The API version that was used in the request |
context=<string> | The context set by the user in the request (optional). |
method="setGlobalFilters" | The requested method. |
data | Empty when the request is successful. |
Return value - Failure
- HTTP Code
200 OK- Content-Type
application/json
{
"apiVersion": "2.1",
"context": "<client context>",
"method": "setGlobalFilters",
"error": {
"code": <integer error code>,
"message": <string>
}
}| Parameter | Description |
apiVersion=<string> | The API version that was used in the request |
context=<string> | The context set by the user in the request (optional). |
method="setGlobalFilters" | The requested method. |
error.code=<integer error code> | The error code. |
error.message=<string> | The error message for the corresponding error code. |
Error codes
See General error codes for a complete list of potential errors.
getGlobalFilters
This method be used when you want to check the current configuration of the global filters.
Request
http://<servername>/axis-cgi/radar/radaranalytics.cgi- Security level
Administrator
- Method
POST
{
"apiVersion": "2.1",
"context": "<client context>",
"method": "getGlobalFilters"
}| Parameter | Description |
apiVersion=<string> | The API version that should be used. |
context=<string> | The user sets this value and the application echoes it back in the response (optional). |
method="getGlobalFilters" | The method that should be used. |
Return value - Success
- HTTP Code
200 OK- Content-Type
application/json
{
"apiVersion": "2.1",
"context": "<client context>",
"method": "getGlobalFilters",
"data": {
"filters": [
{
"type": "FilterOne",
"active": true
},
{
"type": "FilterTwo",
"active": false
}
]
}
}| Parameter | Description |
apiVersion=<string> | The API version that was used in the request |
context=<string> | The context set by the user in the request (optional). |
method="getGlobalFilters" | The requested method. |
filters | An array of objects describing a global filter. Please note that the names FilterOne and FilterTwo used above are examples. There are no filters with those names. |
Return value - Failure
- HTTP Code
200 OK- Content-Type
application/json
{
"apiVersion": "Major.Minor",
"context": <client context>,
"method": "getGlobalFilters",
"error": {
"code": <integer error code>,
"message": <string>
}
}| Parameter | Description |
apiVersion=<string> | The API version that was used in the request |
context=<string> | The context set by the user in the request (optional). |
method="getGlobalFilters" | The requested method. |
error.code=<integer error code> | The error code. |
error.message=<string> | The error message for the corresponding error code. |
Error codes
See General error codes for a complete list of potential errors.
setMountingHeight
This method should be used when you want to set the mounting height of the radar detector.
The mounting height affects the radar analytics algorithm, which means that it is important to set this parameter if the mounting height differs from the default 3.5 meters.
Request
http://myserver/axis-cgi/radar/radaranalytics.cgi- Security level
Operator
- Method
POST
{
"apiVersion": "2.1",
"context": "<client context>",
"method": "setMountingHeight",
"params": {
"value": <mounting height>,
"channel": <radar channel>
}
}| Parameter | Description |
apiVersion=<string> | The API version that should be used. |
context=<string> | The user sets this value and the application echoes it back in the response (optional). |
method="setMountingHeight" | The method that should be used. |
params.value=<number> | The vertical mounting height of the radar detector, measured in meters. The range of permissible values are given by getConfigurationCapabilities. |
params.channel=<integer> | Specifies the radar channel whose mounting height should be set (optional). All radar channels will have their mounting height set to params.value if this parameter is omitted. |
Return value - Success
- HTTP Code
200 OK- Content-Type
application/json
{
"apiVersion": "2.1",
"context": "<client context>",
"method": "setMountingHeight",
"data": {}
}| Parameter | Description |
apiVersion=<string> | The API version that was used in the request |
context=<string> | The context set by the user in the request (optional). |
method="setMountingHeight" | The requested method. |
data | Empty when the request is successful. |
Return value - Failure
- HTTP Code
200 OK- Content-Type
application/json
{
"apiVersion": "2.1",
"context": "<client context>",
"method": "setMountingHeight",
"error": {
"code": <integer error code>,
"message": <string>
}
}| Parameter | Description |
apiVersion=<string> | The API version that was used in the request |
context=<string> | The context set by the user in the request (optional). |
method="setMountingHeight" | The requested method. |
error.code=<integer error code> | The error code. |
error.message=<string> | The error message for the corresponding error code. |
Error codes
See General error codes for a complete list of potential errors.
getMountingHeight
This method should be used when you want to check the current mounting height of the radar detector.
Request
http://myserver/axis-cgi/radar/radaranalytics.cgi- Security level
Operator
- Method
POST
{
"apiVersion": "2.1",
"context": "<client context>",
"method": "getMountingHeight",
"params": {
"channel": <radar channel>
}
}| Parameter | Description |
apiVersion=<string> | The API version that should be used. |
context=<string> | The user sets this value and the application echoes it back in the response (optional). |
method="getMountingHeight" | The method that should be used. |
params.channel | Specifies the radar channel whose mounting height will be returned in the response (optional). The mounting height for radar channel 1 will be returned if this parameter is omitted. |
Return value - Success
- HTTP Code
200 OK- Content-Type
application/json
{
"apiVersion": "2.1",
"context": "<client context>",
"method": "getMountingHeight",
"data": {
"value": <mounting height in meters>
}
}| Parameter | Description |
apiVersion=<string> | The API version that was used in the request |
context=<string> | The context set by the user in the request (optional). |
method="getMountingHeight" | The requested method. |
data.value | The current mounting height for the requested radar channel. |
Return value - Failure
- HTTP Code
200 OK- Content-Type
application/json
{
"apiVersion": "2.1",
"context": "<client context>",
"method": "getMountingHeight",
"error": {
"code": <integer error code>,
"message": <string>
}
}| Parameter | Description |
apiVersion=<string> | The API version that was used in the request |
context=<string> | The context set by the user in the request (optional). |
method="getMountingHeight" | The requested method. |
error.code=<integer error code> | The error code. |
error.message=<string> | The error message for the corresponding error code. |
Error codes
See General error codes for a complete list of potential errors.
setMountingTilt
This method should be used when you wish to set the mounting tilt of the radar detector. Some products may have an automatic source for the tilt measurement, which can be overridden by using this API.
The mounting tilt affects the radar analytics algorithm, which means that it is important to set this parameter if the mounting height differs from the default 0 degrees and should be set relative to the surface that the radar is “seeing”. For a radar mounted on a wall, zero degrees means that the backplane of the device is parallel to the wall and vertical to the ground. If the radar is tilted downwards by 10 degrees, the value 10 should be entered, while if the radar is tilted upwards by 10 degrees, the value -10 should be entered.
Request
http://myserver/axis-cgi/radar/radaranalytics.cgi- Security level
Operator
- Method
POST
{
"apiVersion": "2.1",
"context": "<client context>",
"method": "setMountingTilt",
"params": {
"automatic": <true|false>,
"value": <mounting tilt>,
"channel": <radar channel>
}
}| Parameter | Description |
apiVersion=<string> | The API version that should be used. |
context=<string> | The user sets this value and the application echoes it back in the response (optional). |
method="setMountingTilt" | The method that should be used. |
params.automatic=<boolean> | Indicates whether automatic tilt angle measurement should be used. This can only be true if the device supports this functionality, otherwise an error will be returned. Whether your device supports this functionality can be queried by checking the field mountingTilt.automatic in the response from getConfigurationCapabilities. |
params.value=<number> | The mounting tilt of the radar detector, measured in degrees. Positive values correspond to a radar tilted downwards, while a value of zero means that the radar is level with the surface. Allowed values are provided by getConfigurationCapabilities. This field is ignored if params.automatic is set to true. |
params.channel=<integer> | Specifies the radar channel that should have its mounting tilt set (optional). All radar channels will have their mounting tilt set to params.value if this parameter is omitted. |
Return value - Success
- HTTP code
200 OK- Content-type
application/json
{
"apiVersion": "2.1",
"context": "<client context>",
"method": "setMountingTilt",
"data": {}
}| Parameter | Description |
apiVersion=<string> | The API version that was used in the request |
context=<string> | The context set by the user in the request (optional). |
method="setMountingTilt" | The requested method. |
data | Empty when the request is successful. |
Return value- Failure
- HTTP code
200 OK- Content-type
application/json
{
"apiVersion": "2.1",
"context": "<client context>",
"method": "setMountingTilt",
"error": {
"code": <integer error code>,
"message": <string>
}
}| Parameter | Description |
apiVersion=<string> | The API version that was used in the request |
context=<string> | The context set by the user in the request (optional). |
method="setMountingTilt" | The requested method. |
error.code=<integer error code> | The error code. |
error.message=<string> | The error message for the corresponding error code. |
Error codes
See General error codes for a complete list of potential errors.
getMountingTilt
This method should be used when you want to check the current mounting tilt of the radar detector and whether the radar is configured to use an automatic source for the tilt measurement.
Request
http://myserver/axis-cgi/radar/radaranalytics.cgi- Security level
Operator
- Method
POST
{
"apiVersion": "2.1,"
"context": "<client context>",
"method": "getMountingTilt",
"params": {
"channel": <radar channel>
}
}| Parameter | Description |
apiVersion=<string> | The API version that should be used. |
context=<string> | The user sets this value and the application echoes it back in the response (optional). |
method="getMountingTilt" | The method that should be used. |
params.channel | Specifies the radar channel whose mounting tilt should be returned in the response (optional). The frequency channel for radar channel 1 will be returned if this parameter is omitted. |
Return value - Success
- HTTP code
200 OK- Content-type
application/json
{
"apiVersion": "2.1,"
"context": "<client context>",
"method": "getMountingTilt",
"data": {
"automatic": <true|false>,
"value": <mounting tilt in degrees>
}
}| Parameter | Description |
apiVersion=<string> | The API version that was used in the request |
context=<string> | The context set by the user in the request (optional). |
method="getMountingTilt" | The requested method. |
data.automatic=<true|false> | Indicates if the device is configured to use automatic mounting tilt measurement. |
data.value | The currently configured mounting tilt angle. This value is automatically updated for each request to this method if the physical mounting tilt angle of the device changes when data.automatic is true. |
Return value - Failure
- HTTP code
200 OK- Content-type
application/json
{
"apiVersion": "2.1,"
"context": "<client context>",
"method": "getMountingTilt",
"error": {
"code": <integer error code>,
"message": <string>
}
}| Parameter | Description |
apiVersion=<string> | The API version that was used in the request |
context=<string> | The context set by the user in the request (optional). |
method="getMountingTilt" | The requested method. |
error.code=<integer error code> | The error code. |
error.message=<string> | The error message for the corresponding error code. |
Error codes
See General error codes for a complete list of potential errors.
getRadarDataStatus
This method should be used when you want to check the data reception status from the radar sensor.
Request
http://myserver/axis-cgi/radar/radaranalytics.cgi- Security level
Operator
- Method
POST
{
"apiVersion": "2.1",
"context": "<client context>",
"method": "getRadarDataStatus"
}| Parameter | Description |
apiVersion=<string> | The API version that should be used. |
context=<string> | The user sets this value and the application echoes it back in the response (optional). |
method="getRadarDataStatus" | The method that should be used. |
Return value - Success
- HTTP Code
200 OK- Content-Type
application/json
{
"apiVersion": "2.1",
"context": "<client context>",
"method": "getRadarDataStatus"
"data": {
"value": false
}
}| Parameter | Description |
apiVersion=<string> | The API version that was used in the request |
context=<string> | The context set by the user in the request (optional). |
method="getRadarDataStatus" | The requested method. |
data.value | true = Data is received from the radar sensor.false = No data is received from the radar sensor. Sensor may be malfunctioning. |
Return value - Failure
- HTTP Code
200 OK- Content-Type
application/json
{
"apiVersion": "2.1",
"context": "<client context>",
"method": "getRadarDataStatus"
"error": {
"code": <integer error code>,
"message": <string>
}
}| Parameter | Description |
apiVersion=<string> | The API version that was used in the request |
context=<string> | The context set by the user in the request (optional). |
method="getRadarDataStatus" | The requested method. |
error.code=<integer error code> | The error code. |
error.message=<string> | The error message for the corresponding error code. |
Error codes
See General error codes for a complete list of potential errors.
getSupportedVersions
This method should be used when you want to retrieve a list of supported API versions.
Request
http://<servername>/axis-cgi/radar/control.cgi- Security level
Administrator
- Method
POST
{
"apiVersion": "2.1",
"context": "<client context>",
"method": "getSupportedVersions"
}| Parameter | Description |
apiVersion=<string> | The API version that should be used. |
context=<string> | The user sets this value and the application echoes it back in the response (optional). |
method="getSupportedVersions" | The method that should be used. |
Return value - Success
- HTTP Code
200 OK- Content-Type
application/json
{
"apiVersion": "2.1",
"context": "<client context>",
"method": "getSupportedVersions"
"data": {
"apiVersions": [
"<Major1>.<Minor1>",
"<Major2>.<Minor2>"
]
}
}| Parameter | Description |
apiVersion=<string> | The API version that was used in the request |
context=<string> | The context set by the user in the request (optional). |
method="getSupportedVersions" | The requested method. |
data.apiVersions=<array of strings> | List of supported major API versions along with their highest minor version ("1.3", "2.1"). |
Return value - Failure
- HTTP Code
200 OK- Content-Type
application/json
{
"apiVersion": "2.1",
"context": "<client context>",
"method": "getSupportedVersions"
"error": {
"code": <integer error code>,
"message": <string>
}
}| Parameter | Description |
apiVersion=<string> | The API version that was used in the request |
context=<string> | The context set by the user in the request (optional). |
method="getSupportedVersions" | The requested method. |
error.code=<integer error code> | The error code. |
error.message=<string> | The error message for the corresponding error code. |
Error codes
See General error codes for a complete list of potential errors.
General error codes
The following table will list all potential errors that may occur for radaranalytics.cgi.
| Code | Description |
1000 | Invalid parameter value. |
4000 | The provided input was not well-formed JSON. |
4001 | A mandatory input parameter was not found in the input. |
4002 | The type of value of a provided JSON parameter was incorrect. |
4004 | The format of a provided JSON parameter was incorrect. |
7000 | The requested API version is not supported by this implementation. |
8000 | Internal error. |
Events
RMD event
Declaration of the RMD event
Declarations for the RMD (radar motion detection) events can be accessed through either VAPIX or ONVIF event web service API:s.
<tnsaxis:RadarSource>
<MotionAlarm wstop:topic="true">
<ChannelXProfileY wstop:topic="true" aev:NiceName="RMD: <profile.name>">
<aev:MessageInstance aev:isProperty="true">
<aev:DataInstance>
<aev:SimpleItemInstance Type="xsd:boolean" Name="active" aev:isPropertyState="true"/>
</aev:DataInstance>
</aev:MessageInstance>
</ChannelXProfileY>
</MotionAlarm>
</tnsaxis:RadarSource>The event in this example is called ChannelXProfileY and is sent every time an object has entered a specific include area. It is based on a profile with channel=X and uid=Y.
The following properties can be used to match the criteria and trigger an action rule:
| Parameter | Description |
Property=<active> | Activates the event when movement is detected in the area and deactivates when the movement disappears. |
<active> | A stateful event. An active event has the value 1, an inactive 0. |
RMD events for multichannel products
This example will show you how an event declaration will look in a scenario where a multichannel product consisting of two channels with two profiles each is used.
<tnsaxis:RadarSource>
<MotionAlarm wstop:topic="true">
<Channel1Profile1 wstop:topic="true" aev:NiceName="RMD: Garden Left">
<aev:MessageInstance aev:isProperty="true">
<aev:DataInstance>
<aev:SimpleItemInstance Type="xsd:boolean" Name="active" aev:isPropertyState="true" />
</aev:DataInstance>
</aev:MessageInstance>
</Channel1Profile1>
<Channel1Profile2 wstop:topic="true" aev:NiceName="RMD: Garden Right">
<aev:MessageInstance aev:isProperty="true">
<aev:DataInstance>
<aev:SimpleItemInstance Type="xsd:boolean" Name="active" aev:isPropertyState="true" />
</aev:DataInstance>
</aev:MessageInstance>
</Channel1Profile2>
<Channel2Profile3 wstop:topic="true" aev:NiceName="RMD: Parking Day">
<aev:MessageInstance aev:isProperty="true">
<aev:DataInstance>
<aev:SimpleItemInstance Type="xsd:boolean" Name="active" aev:isPropertyState="true"/>
</aev:DataInstance>
</aev:MessageInstance>
</Channel2Profile3>
<Channel2Profile4 wstop:topic="true" aev:NiceName="RMD: Parking Night">
<aev:MessageInstance aev:isProperty="true">
<aev:DataInstance>
<aev:SimpleItemInstance Type="xsd:boolean" Name="active" aev:isPropertyState="true" />
</aev:DataInstance>
</aev:MessageInstance>
</Channel2Profile4>
</MotionAlarm>
</tnsaxis:RadarSource>ChannelXProfileANY event
When the radar detects an object entering an include area an ANY event element will be sent for a specific channel.
<tnsaxis:RadarSource>
<MotionAlarm wstop:topic="true">
<ChannelXProfileANY wstop:topic="true" aev:NiceName="RMD: Any Profile">
<aev:MessageInstance aev:isProperty="true">
<aev:DataInstance>
<aev:SimpleItemInstance Type="xsd:boolean" Name="active" aev:isPropertyState="true" />
</aev:DataInstance>
</aev:MessageInstance>
</ChannelXProfileANY>
</MotionAlarm>
</tnsaxis:RadarSource>The event in this example is named ChannelXProfileANY and it is sent every time an object enters a specific include area. It is based on a profile with channel=X.
ChannelANY event
When the radar detects an object entering an include area a global ANY event element will be sent. This means that alarms appearing on one of the channels will trigger the global ANY event on all channels.
<tnsaxis:RadarSource>
<MotionAlarm wstop:topic="true">
<ChannelANY wstop:topic="true" aev:NiceName="RMD: Any Channel">
<aev:MessageInstance aev:isProperty="true">
<aev:DataInstance>
<aev:SimpleItemInstance Type="xsd:boolean" Name="active" aev:isPropertyState="true" />
</aev:DataInstance>
</aev:MessageInstance>
</ChannelANY>
</MotionAlarm>
</tnsaxis:RadarSource>The event stream
A user may subscribe to events from the VAPIX/ONVIF event stream and receive information about the format of both the stream and its elements in http://www.onvif.org/onvif/ver10/schema/onvif.xsd and http://www.onvif.org/onvif/ver10/topics/topicns.xml.
Using VAPIX, this stream can be retrieved over RTSP using the following URL:
rtsp://<servername>/axis-media/media.amp?event=on&eventtopic=tnsaxis:RadarSource/MotionAlarm//It is also possible to listen for a specific profile:
rtsp://<servername>/axis-media/media.amp?event=on&eventtopic=tnsaxis:RadarSource/MotionAlarm/ChannelXProfileY/Synchronize metadata with video stream
Axis radar sensors uses the Real Time Streaming Protocl (RTSP) to control the media stream between radar and clients. RTSP implements the Realtime Transport Protocol (RTP) for the packet format when streaming the meta/video data, and the RTP Control Protocol (RTCP) for the synchronization of the metadata and video data stream. The synchronized conversation, from the absolute time (UTC timestamp) at the motion detection, to the relative time (RTP timestamp) for the video stream, can be found in the RTCP packet.
ONVIF MotionAlarm event
Declaration of the MotionAlarm event
The declaration of the ONVIF Motion Alarm event can be accessed through either the VAPIX or ONVIF event web service API. ONVIF events corresponds to the ChannelXProfileANY event and will be sent if there is an ANY event sent to a specific channel.
<tns1:VideoSource>
<MotionAlarm wstop:topic="true">
<tt:MessageDescription IsProperty="true">
<tt:Source>
<tt:SimpleItemDescription Name="Source" Type="tt:ReferenceToken"/>
</tt:Source>
<tt:Data>
<tt:SimpleItemDescription Name="State" Type="xs:boolean"/>
</tt:Data>
</tt:MessageDescription>
</MotionAlarm>
</tns1:VideoSource>| Parameter | Description |
Property=<Source> | The ONVIF Video source starting at 0. |
<Source> | Reference counter starts at 0. |
Property=<Data> | The value for the motion alarm state. |
<State> | An active event has the value 1, an inactive 0. |
The event stream
A user may subscribe to events from the VAPIX/ONVIF event stream. The format of both the stream and its elements are described in http://www.onvif.org/onvif/ver10/schema/onvif.xsd and http://www.onvif.org/onvif/ver10/topics/topicns.xml.
Using VAPIX, this stream can be retrieved over RTSP with the following URL:
rtsp://<servername>/axis-media/media.amp?event=on&eventtopic=tns1:VideoSource/MotionAlarm//It is also possible to listen for a specific profile with the following URL:
rtsp://<servername>/axis-media/media.amp?event=on&eventtopic=tnsaxis:RadarSource/MotionAlarm/ChannelXProfileY/System event
Radar data disruption event
Radar data errors uses the tag format_modifier_user_string in notifications for radar data disruption events to return a user friendly explanation on what went wrong. The channel with the value -1 and the nicename Any will be used as the combined status for all channels.
<tns1:Device aev:NiceName="Device">
<tnsaxis:HardwareFailure aev:NiceName="Hardware failure">
<RadarFailure wstop:topic="true" aev:NiceName="Radar data failure">
<aev:MessageInstance aev:isProperty="true">
<aev:SourceInstance>
<aev:SimpleItemInstance aev:NiceName="Channel Identifier" Type="xsd:int" Name="channel">
</aev:SourceInstance>
<aev:DataInstance>
<aev:SimpleItemInstance aev:NiceName="Reason Code" Type="xsd:int" Name="reason"/>
<aev:SimpleItemInstance aev:NiceName="Reason Description" Type="xsd:string" Name="reasonstr"/>
<aev:SimpleItemInstance aev:NiceName="Radar Data Disruption" Type="xsd:boolean" Name="disruption" isPropertyState="true"/>
</aev:DataInstance>
</aev:MessageInstance>
</RadarFailure>
</tnsaxis:HardwareFailure>
</tns1:Device>| Code | Description |
0 | No radar data. |
1 | Radar interference. |
Event actions
Activate radar action
This action should be used when you want to turn the radar detection either on or off by using one of the following options:
fixed action: keeps the radar either on or off for a predefined time set by parameters .
unlimited action: keeps the radar either on or off as long as all event conditions are fulfilled.
Action id
com.axis.action.fixed.radarcom.axis.action.unlimited.radar
| Parameters | Valid values | Description |
state | 0, 1 | 0 = Radar detection is off. 1 = Radar detection is on. |
duration | Unsigned integer | Fixed actions: The number of seconds that keeps the radar either on or off. |
Metadata
The metadata stream
All users are able to subscribe to a metadata stream from the VAPIX and ONVIF analytics web service detailed in https://www.onvif.org/specs/srv/analytics/ONVIF-Analytics-Service-Spec-v241.pdf.
Using VAPIX, this stream can be retrieved over RTSP with the following URL:
rtsp://<servername>/axis-media/media.amp?video=0&audio=0&event=off&analytics=polygonAn XML frame may contain several object elements corresponding to a tracked object. Frames with no detected objects are sent as empty frames.
Radar extension description
This extension has been deprecated and will no longer receive any updates. We recommend that you use the following ONVIF fields instead:
Use the standardized GeoLocation field instead of the GeoLocation extension.
Use the SphericalCoordinate field instead of the PolarCoordinate extension.
Use the Speed and Direction fields located under Behaviour instead of the Velocity extenstion.
This metadata stream contains an extension for radar-specific data where <tt:Appearance> contains a radar extension for the radar object info:
<tt:Extension>
<axrt:RadarObjectInfo>
<axrt:PolarCoordinate angle="0.0" range="0.0"/>
<axrt:Velocity m-s="0.0" angle="0.0"/>
<axrt:Size m="0.0"/>
</axrt:RadarObjectInfo>
</tt:Extension>| Parameter | Description |
PolarCoordinate | The angle and range where the object is located according to the position of the radar sensor. Range is given in meters and angle in degrees where 0° is straight ahead of the sensor. |
Velocity | The speed and direction of the object, where direction is the bearing relative to the radar sensor measured in degrees. |
Size | The size of the detected object, measured in meters. |
<tt:Class> includes an extension when the type under <tt:ClassCandidate> is Other.
<tt:Extension>
<tt:OtherTypes>
<tt:Type>Unknown</tt:Type>
<tt:Likelihood>1.0</tt:Likelihood>
</tt:OtherTypes>
</tt:Extension>In this case, type can be:
UnknownSmallObject
Declaration of the metadata stream
The following example will show you how a metadata frame may look for a scenario when multiple objects are tracked.
<tt:MetadataStream xmlns:tt="http://www.onvif.org/ver10/schema">
<tt:VideoAnalytics>
<tt:Frame UtcTime="2017-07-14T08:45:20.284189Z">
<tt:Object ObjectId="88">
<tt:Appearance>
<tt:Shape>
<tt:BoundingBox bottom="-0.438904" top="-0.458923" right="0.130005" left="0.109985" />
<tt:CenterOfGravity x="0.109985" y="-0.458923" />
<tt:Polygon>
<tt:Point x="0.099976" y="-0.468933" />
<tt:Point x="0.119995" y="-0.468933" />
<tt:Point x="0.119995" y="-0.448914" />
<tt:Point x="0.099976" y="-0.448914" />
</tt:Polygon>
</tt:Shape>
<tt:Class>
<tt:ClassCandidate>
<tt:Type>Other</tt:Type>
<tt:Likelihood>0.80</tt:Likelihood>
</ClassCandidate>
<tt:Extension>
<tt:OtherTypes>
<tt:Type>Unknown</tt:Type>
<tt:Likelihood>1.0</tt:Likelihood>
</tt:OtherTypes>
</tt:Extension>
<tt:Type Likelihood="0.75">Vehicle</tt:Type>
</tt:Class>
<tt:Extension>
<axrt:RadarObjectInfo xmlns:axrt="http://www.axis.com/2017/radar/axrt">
<axrt:PolarCoordinate angle="23.91" range="14.49" />
<axrt:Velocity m-s="1.05" angle="343.60" />
<axrt:Size m="0.00" />
</axrt:RadarObjectInfo>
<tt:GeoLocation lon="0.0000528" lat="0.0001196" elevation="0" />
</tt:Extension>
<tt:GeoLocation lon="0.0000528" lat="0.0001196" elevation="0" />
<tt:SphericalCoordinate Distance="14.49" ElevationAngle="0.0" AzimuthAngle="66.09"/>
<tt:Behaviour>
<tt:Speed>1.05</tt:Speed>
<tt:Direction yaw="106.4" pitch="0"/>
</tt:Behaviour>
</tt:Appearance>
</tt:Object>
<tt:Object ObjectId="84">
...
</tt:Object>
</tt:Frame>
</tt:VideoAnalytics>
</tt:MetadataStream>