Skip to main content

Autopilot API

This API is based on the Device Configuration API framework. For guidance on how to use these APIs, please refer to Device Configuration APIs.

The VAPIX® Autopilot API makes it possible to configure the PTZ camera's autopilot. This includes configuration of the tracking behavior, what to track and controlling of the calibration process.

Overview​

Autopilot is a tracking application that tracks moving objects based on incoming data from AOA (AXIS Object Analytics). Autopilot needs to be enabled and configured.

Authentication​

For detailed information on how to authenticate requests to this API, please refer to Authentication.

Use cases​

Verify that Autopilot is not in solo mode​

Assure that the product is not in solo mode. Solo mode means that there is no remote PTZ connected, since Autopilot only works when the device isn't in solo mode. It can be checked with the following request:

curl --request GET \
  --anyauth \
  --user "<username>:<password>" \
  --http1.1 \
  --header "Content-Type: application/json" \
  http://my-device/config/rest/autopilot/v1/inSoloMode
200 OK
Content-Type: application/json

{
    "status": "success",
    "data": false
}

Configure the autopilot​

Configure the Autopilot before enabling tracking. This triggers a state change:

curl --request PATCH \
  --anyauth \
  --user "<username>:<password>" \
  --http1.1 \
  --header "Content-Type: application/json" \
  http://my-device/config/rest/autopilot/v1/enable \
  --data '{
    "data": true
}'
200 OK
Content-Type: application/json

{
    "status": "success"
}

Once enabled, the Autopilot returns its current state. Any failures during initialization will return a failure state. For example, failure to connect to a remote PTZ will result in the following response:

curl --request GET \
  --anyauth \
  --user "<username>:<password>" \
  --http1.1 \
  --header "Content-Type: application/json" \
  http://my-device/config/rest/autopilot/v1/state
200 OK
Content-Type: application/json

{
    "status": "success",
    "data": "connectToPtzFailed"
}

A successfully enabled Autopilot requires calibration, which is reflected in its state:

curl --request GET \
  --anyauth \
  --user "<username>:<password>" \
  --http1.1 \
  --header "Content-Type: application/json" \
  http://my-device/config/rest/autopilot/v1/state
200 OK
Content-Type: application/json

{
    "status": "success",
    "data": "calibrationNeeded"
}

Calibration process​

The calibration process identifies the internal mechanical properties of the connected remote PTZ camera and receives the optimal control parameters. This allows for optimal tracking for the connected remote PTZ. The calibration process is a requirement before tracking can be enabled. To start the calibration process use:

curl --request POST \
  --anyauth \
  --user "<username>:<password>" \
  --http1.1 \
  --header "Content-Type: application/json" \
  http://my-device/config/rest/autopilot/v1/calibration/start \
  --data '{
    "data": {}
}'
200 OK
Content-Type: application/json

{
    "status": "success",
    "data": {}
}

A successful calibration will return the following status:

curl --request GET \
  --anyauth \
  --user "<username>:<password>" \
  --http1.1 \
  --header "Content-Type: application/json" \
  http://my-device/config/rest/autopilot/v1/calibration/status
200 OK
Content-Type: application/json

{
    "status": "success",
    "data": "calibrated"
}

Verify that the channels are calibrated​

The autopilot will not work correctly without channel calibration, which can be performed with the camera's setup assistant. It can be checked with the following call:

curl --request GET \
  --anyauth \
  --user "<username>:<password>" \
  --http1.1 \
  --header "Content-Type: application/json" \
  http://my-device/config/rest/autopilot/v1/calibration/channelsCalibrated
200 OK
Content-Type: application/json

{
    "status": "success",
    "data": [
        {
            "calibrated": true,
            "channelId": 1
        },
        {
            "calibrated": true,
            "channelId": 2
        },
        {
            "calibrated": true,
            "channelId": 3
        },
        {
            "calibrated": true,
            "channelId": 4
        }
    ]
}

Configure scenario​

Autopilot scenarios need to be configured before they can determine what objects to track. Scenarios are created with AXIS Object Analytics and determine the condition of the objects that should be detected, such as include zones, object types, etc. To configure a scenario, provide its ID, the channel ID it was created for, the object priority, and whether it should be enabled. Multiple scenarios can be configured at once, for example:

curl --request PATCH \
  --anyauth \
  --user "<username>:<password>" \
  --http1.1 \
  --header "Content-Type: application/json" \
  http://my-device/config/rest/autopilot/v1/scenarioConfiguration/scenarios \
  --data '{
    "data": [
        {
            "scenarioId": 1,
            "channelId": 1,
            "enabled": true,
            "priority": 10
        },
        {
            "scenarioId": 2,
            "channelId": 2,
            "enabled": false,
            "priority": 1
        }
    ]
}'
200 OK
Content-Type: application/json

{
    "status": "success"
}

Enable object switching​

The remote PTZ camera can only track one object at a time. Autopilot can be configured to track multiple active objects, with a timer deciding how long an object is tracked. This example shows an object switch with a tracking time of 15 seconds:

curl --request PATCH \
  --anyauth \
  --user "<username>:<password>" \
  --http1.1 \
  --header "Content-Type: application/json" \
  http://my-device/config/rest/autopilot/v1/objectSwitch \
  --data '{
    "data": {
        "enabled": true,
        "time": 15
    }
}'
200 OK
Content-Type: application/json

{
    "status": "success"
}

API definition​

Structure​

autopilot.v1 (Root Entity)
    ├── enabled (Property)
    ├── inSoloMode (Property)
    ├── state (Property)
    ├── calibration (Entity)
        ├── channelsCalibrated (Property)
        ├── status (Property)
        ├── abort (Action)
        ├── start (Action)
    ├── objectSwitch (Entity)
        ├── enabled (Property)
        ├── time (Property)
    ├── scenarioConfiguration (Entity)
        ├── scenarios (Property)

Entities​

autopilot.v1​

  • Description: The Autopilot configuration.
  • Type: Singleton
  • Operations
    • Get
    • Set
  • Attributes
    • Dynamic Support: No
Properties​
enabled​
  • Description: Turn on or off the Autopilot.
  • Datatype: boolean
  • Operations
    • Get (Permissions: admin)
    • Set (Permissions: admin)
  • Attributes
    • Nullable: No
    • Dynamic Support: No / Dynamic Enum: No / Dynamic Range: No
inSoloMode​
  • Description: Get if the Autopilot is in solo mode, i.e. when there is no connected remote PTZ.
  • Datatype: boolean
  • Operations
    • Get (Permissions: admin)
  • Attributes
    • Nullable: No
    • Dynamic Support: No / Dynamic Enum: No / Dynamic Range: No
state​
  • Description: Get the current state of Autopilot.
  • Datatype: AutopilotState
  • Operations
    • Get (Permissions: admin)
  • Attributes
    • Nullable: No
    • Dynamic Support: No / Dynamic Enum: No / Dynamic Range: No
Actions​

This entity has no actions.

autopilot.v1.calibration​

  • Description: Control the calibration process.
  • Type: Singleton
  • Operations
    • Get
  • Attributes
    • Dynamic Support: No

This entity contains the properties and actions that manage the calibration process. The property for the current status reflects the actions performed on the entity.

Properties​
channelsCalibrated​
  • Description: Get a list of channels IDs and if they are calibrated to the remote PTZ.
  • Datatype: ChannelsCalibrated
  • Operations
    • Get (Permissions: admin)
  • Attributes
    • Nullable: No
    • Dynamic Support: No / Dynamic Enum: No / Dynamic Range: No
status​
  • Description: Get the current calibration status.
  • Datatype: CalibrationStatus
  • Operations
    • Get (Permissions: admin)
  • Attributes
    • Nullable: No
    • Dynamic Support: No / Dynamic Enum: No / Dynamic Range: No
Actions​
abort​
start​

autopilot.v1.objectSwitch​

  • Description: Configure object switch for the Autopilot. This enables the Autopilot to switch tracking between objects, with a fixed time.
  • Type: Singleton
  • Operations
    • Get
    • Set
      • Properties: enabled, time
  • Attributes
    • Dynamic Support: No
Properties​
enabled​
  • Description: Enable object switching on or off.
  • Datatype: boolean
  • Operations
    • Get (Permissions: admin)
    • Set (Permissions: admin)
  • Attributes
    • Nullable: No
    • Dynamic Support: No / Dynamic Enum: No / Dynamic Range: No
time​
  • Description: Change the object switching time.
  • Datatype: ObjectSwitchTime
  • Operations
    • Get (Permissions: admin)
    • Set (Permissions: admin)
  • Attributes
    • Nullable: No
    • Dynamic Support: No / Dynamic Enum: No / Dynamic Range: No
Actions​

This entity has no actions.

autopilot.v1.scenarioConfiguration​

  • Description: Configure the scenarios.
  • Type: Singleton
  • Operations
    • Get
  • Attributes
    • Dynamic Support: No
Properties​
scenarios​
  • Description: Scenarios that configures which objects to track.
  • Datatype: ScenariosData
  • Operations
    • Get (Permissions: admin)
    • Set (Permissions: admin)
  • Attributes
    • Nullable: No
    • Dynamic Support: No / Dynamic Enum: No / Dynamic Range: No
Actions​

This entity has no actions.

Data Types​

AbortCalibrationRequest​

  • Description: Abort calibration request data.
  • Type: complex

AbortCalibrationResponse​

  • Description: Abort calibration response data.
  • Type: complex

AutopilotState​

  • Description: The current state of the Autopilot.
  • Type: string
  • Enum Values: "autotuneFailed", "autotuneRetry", "autotuning", "calibrationNeeded", "checkCalibration", "checkCalibrationRemoteConnection", "checkCalibrationRemoteConnectionFailed", "checkZoom", "checkZoomFailed", "connectToPtz", "connectToPtzFailed", "disabled", "gotoStartPosition", "gotoStartPositionFailed", "paused", "running", "soloMode", "soloModeError", "start", "startCalibration", "waitingForPtz"

CalibrationStatus​

  • Description: The current calibration status.
  • Type: string
  • Enum Values: "uncalibrated", "calibrated", "calibrating", "calibrationFailed"

ChannelCalibrated​

  • Description: Data if a channel is calibrated to the connected remote PTZ.
  • Type: complex
  • Fields
    • calibrated
      • Description: If the channel is calibrated.
      • Type: boolean
      • Nullable: No / Gettable: Yes
    • channelId
      • Description: The channel ID.
      • Type: ChannelId
      • Nullable: No / Gettable: Yes

ChannelId​

  • Description: Channel Id value.
  • Type: integer

ChannelsCalibrated​

  • Description: A list of channels and if they are calibrated.
  • Type: array
  • Element type: ChannelCalibrated
  • Null Value: No

ObjectSwitchTime​

  • Description: The object switch time, in seconds.
  • Type: integer
  • Minimum Value: 0
  • Maximum Value: 60

ScenarioData​

  • Description: Data to configure a scenario.
  • Type: complex
  • Fields
    • channelId
      • Description: Channel Id to which the scenario corresponds to.
      • Type: ChannelId
      • Nullable: No / Gettable: Yes
    • enabled
      • Description: Enable tracking for the scenario.
      • Type: boolean
      • Nullable: No / Gettable: Yes
    • priority
      • Description: Priority of the scenario, higher values signifies higher priority.
      • Type: ScenarioPriority
      • Nullable: No / Gettable: Yes
    • scenarioId
      • Description: Scenario Id to which the scenario corresponds to.
      • Type: ScenarioId
      • Nullable: No / Gettable: Yes

ScenarioId​

  • Description: Scenario Id value.
  • Type: integer

ScenarioPriority​

  • Description: Priority value, higher values means a higher priority.
  • Type: integer
  • Minimum Value: 1
  • Maximum Value: 20

ScenariosData​

  • Description: Data to configure a list of scenarios.
  • Type: array
  • Element type: ScenarioData
  • Null Value: No

StartCalibrationRequest​

  • Description: Start calibration request data.
  • Type: complex

StartCalibrationResponse​

  • Description: Start calibration response data.
  • Type: complex