Skip to main content

Device mode configuration

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

warning

This API is in BETA stage. The API is provided for testing purposes and is subject to backward-incompatible changes, including modifications to functionality, behavior, and availability. Please don't use in production environment.

The VAPIX® Device mode configuration API allows you to manage different operating modes for the device. You can list all available device modes, check which mode is currently active, and set the mode to switch to. Each device mode is identified by a short descriptive string ID (fisheye, double-panorama, etc.).

The API provides properties on the root entity:

  • activeMode - The device mode that is currently active on the device.
  • mode - The pending device mode if different than activeMode, otherwise it has the same device mode as the activeMode.
  • restartRequired - Boolean property that indicates whether a restart is needed when mode differs from activeMode.

The restartRequired property indicates whether a restart is needed for the change to take effect. In current implementations, this is typically true, but future implementations could support dynamic mode switching without requiring a restart, in which case restartRequired would be false. If restartRequired is true, you can revert the change by setting mode back to match activeMode, which will set restartRequired to false.

Please note that when changing mode the device might change its behavior.

Use cases​

Get the root entity​

Use the root entity to check the desired mode, as well as the active mode, restart status and other available modes.

Here is an example of how to get the root entity.

GET /config/rest/device-mode/v1beta HTTP/1.1
HOST: my-device
Content-Type: application/json
HTTP/1.1 200 OK
Content-Type: application/json

{
    "status": "success",
    "data": {
        "activeMode": "fisheye",
        "mode": "fisheye",
        "restartRequired": false,
        "availableModes": {
            "fisheye": {
                "id": "fisheye"
            },
            "double-panorama": {
                "id": "double-panorama"
            }
        }
    }
}

Get the mode​

Get the mode property to check which device mode has been set.

Here is an example of how to get the mode.

GET /config/rest/device-mode/v1beta/mode HTTP/1.1
HOST: my-device
Content-Type: application/json
HTTP/1.1 200 OK
Content-Type: application/json

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

Get the active mode​

Use the activeMode property to check which device mode is currently running.

Here is an example of how to get the active mode.

curl --request GET \
  --anyauth \
  --user "<username>:<password>" \
  --http1.1 \
  --header "Content-Type: application/json" \
  http://my-device/config/rest/device-mode/v1beta/activeMode
HTTP/1.1 200 OK
Content-Type: application/json

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

Get all available device modes​

Get the availableModes entity collection to check all available device modes.

Here is an example of how to get all available modes.

curl --request GET \
  --anyauth \
  --user "<username>:<password>" \
  --http1.1 \
  --header "Content-Type: application/json" \
  http://my-device/config/rest/device-mode/v1beta/availableModes
HTTP/1.1 200 OK
Content-Type: application/json

{
    "status": "success",
    "data": {
        "fisheye": {
            "id": "fisheye"
        },
        "double-panorama": {
            "id": "double-panorama"
        }
    }
}

Get a specific available mode​

Get a specific mode from the availableModes collection.

Here is an example of how to get a specific mode.

curl --request GET \
  --anyauth \
  --user "<username>:<password>" \
  --http1.1 \
  --header "Content-Type: application/json" \
  http://my-device/config/rest/device-mode/v1beta/availableModes/double-panorama
HTTP/1.1 200 OK
Content-Type: application/json

{
    "status": "success",
    "data": {
        "id": "double-panorama"
    }
}

Change device mode​

Set the desired device mode. Check the restartRequired property to determine if a device restart is required for the change to take effect.

Here is an example of how to set the device mode.

curl --request PATCH \
  --anyauth \
  --user "<username>:<password>" \
  --http1.1 \
  --header "Content-Type: application/json" \
  http://my-device/config/rest/device-mode/v1beta/mode \
  --data '{
    "data": "double-panorama"
}'
HTTP/1.1 200 OK
Content-Type: application/json

{
    "status": "success"
}

After changing the mode, you should:

  • GET the restartRequired property to check if a restart is needed.
  • If restartRequired is true, you have two options:
    • Restart the device for the change to take effect.
    • The mode will become the activeMode after the restart.
  • Revert the change by setting mode back to activeMode.

Revert pending mode change​

Revert a pending device mode change before restarting. This makes it possible to cancel the mode change if restartRequired is true.

This example will show you how to revert a pending mode change when the current mode is "fisheye" and the desired mode was set to "double-panorama":

curl --request PATCH \
  --anyauth \
  --user "<username>:<password>" \
  --http1.1 \
  --header "Content-Type: application/json" \
  http://my-device/config/rest/device-mode/v1beta/mode \
  --data '{
    "data": "fisheye"
}'
HTTP/1.1 200 OK
Content-Type: application/json

{
    "status": "success"
}

After reverting, the mode will match the active mode, and restartRequired will be false:

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

{
    "status": "success",
    "data": {
        "activeMode": "fisheye",
        "mode": "fisheye",
        "restartRequired": false,
        "availableModes": {
            "fisheye": {
                "id": "fisheye"
            },
            "double-panorama": {
                "id": "double-panorama"
            }
        }
    }
}

Restart the device​

Restart the device to apply the preferred device mode when restartRequired is true.

To restart the device, use the firmware management CGI endpoint:

POST http://<servername>/axis-cgi/firmwaremanagement.cgi

Request body:

{
    "apiVersion": "1.0",
    "method": "reboot"
}

Example:

curl -X POST http://192.168.0.90/axis-cgi/firmwaremanagement.cgi -H "Content-Type: application/json" --digest -u user:password -d '{"apiVersion": "1.0", "method": "reboot"}'

API definition​

Structure​

device-mode.v1 (Root Entity)
    ├── activeMode (Property)
    ├── mode (Property)
    ├── restartRequired (Property)
    ├── availableModes (Entity Collection)
        ├── id (Property)

Entities​

device-mode.v1​

  • Description: The device mode root entity
  • Type: Singleton
  • Operations
    • GET
  • Attributes
    • Dynamic Support: No
Properties​
activeMode​
  • Description: The device mode that is currently active
  • Datatype: ModeId
  • Operations
    • GET (Permissions: admin, operator, viewer)
  • Attributes
    • Nullable: No
    • Dynamic Support: No / Dynamic Enum: No / Dynamic Range: No
mode​
  • Description: The pending device mode if different from activeMode, otherwise same as activeMode
  • Datatype: ModeId
  • Operations
    • GET (Permissions: admin, operator, viewer)
    • SET (Permissions: admin)
  • Attributes
    • Nullable: No
    • Dynamic Support: No / Dynamic Enum: No / Dynamic Range: No
restartRequired​
  • Description: Indicates if a restart is required to apply the mode change. This is typically true for current implementations.
  • Datatype: boolean
  • Operations
    • GET (Permissions: admin, operator, viewer)
  • Attributes
    • Nullable: No
    • Dynamic Support: No / Dynamic Enum: No / Dynamic Range: No
Actions​

This entity has no actions.

device-mode.v1.availableModes​

  • Description: The availableModes entity collection contains all device modes that are available on the device. Each mode is accessed by its ID (fisheye, double-panorama, etc.).

  • Type: Collection (Key Property: id)

  • Operations

    • GET

  • Attributes

    • Dynamic Support: No

  • Fields:

    • id - The device mode identifier as a short descriptive string
Properties​
id​
  • Description: The device mode identifier (short descriptive string)
  • Datatype: ModeId
  • Operations
    • GET (Permissions: admin, operator, viewer)
  • Attributes
    • Nullable: No
    • Dynamic Support: No / Dynamic Enum: No / Dynamic Range: No
Actions​

This entity has no actions.

Data Types​

ModeId​

  • Description: The device mode identifier as a short descriptive string (fisheye, double-panorama, etc.)
  • Type: string
  • Minimum Length: 2
  • Maximum Length: 32
  • Pattern: ^[a-z][a-z0-9-]*$
Last updated on