Supervised I/O

Description

The Supervised I/O API provides you with you information that makes it possible to set up the I/O so that tampering can be detected on your device and add additional I/O states. In order to configure the supervised I/O you must first define the upper and lower limits, also known as ranges, for each state. These ranges are hardware dependent, as different hardware has different values to detect errors, such as shorted or cut cables and is implemented with end-of-line resistors in alarm circuits.

The API has two supported versions, referred to as version 1.0 and 2.0. What this means is that 1.0 is still fully supported for anyone not in a position to update , but any new implementation must be done in 2.0. The 2 main differences between API versions are:

The error codes in 2.0 uses a 4 digit structure with codes divided into different ranges..
Different OK response for the setSupervised method.

Model

The API consists of the CGI supervisedio.cgi and the following methods:

Method	Description
`getNumberOfPorts`	Ask for the number of available in- and output ports on the system.
`isSupervisable`	Check if a port can be supervised.
`setSupervised`	Pick a port using the previous methods and set it to supervised.

At this point, you are required use the following method to set the proper ranges (upper and lower limits) for the different states:

Method	Description
`getSupportedStates`	Receive information about supported states in the system. Available states are `open`, `close`, `cut` and `shorted`.

The API also provides interfaces to receive current configurations, which is done with the following methods:

Method	Description
`getSupervised`	Check if a port is supervised.
`getSupervisedRanges`	Check the current ranges of each state. You can receive information about the current state and level of the supervised system by using the method `getSupervised`.

Identification

Property: Properties.API.HTTP.Version=3
Property: Properties.SupervisedIO.SupervisedIO=yes
Property: Properties.SupervisedIO.Version=2.00
Firmware: 7.10 and later
API Discovery: id=supervised-io

Common examples

Setup supervision of an I/O port

Use this example to set up supervision for a peripheral connected to the AXIS device via I/O. This makes it possible for the device to detect tampering such as if someone tries to cut or shorten the cables. You can also:

determine if an I/O port can be set up as supervised.
configure different trigger levels for when a cable is cut or shorted (depending of the electrical configuration of the device).

1) Get the number of input- and output ports in the system:

http://myserver/axis-cgi/supervisedio.cgi

JSON request example

{
  "apiVersion": "2.0",
  "method": "getNumberOfPorts"
}

2) Parse the JSON response. The response will present information on the number of input- and output ports.

{
  "apiVersion": "2.0",
  "method": "getNumberOfPorts",
  "data": {
    "inputs": 2,
    "outputs": 2
  }
}

3) Get information if a port can be supervised:

{
  "apiVersion": "2.0",
  "method": "isSupervisable"
}

4) Parse the JSON response. The response presents information on which of the ports is a supervised input/output.

{
  "apiVersion": "2.0",
  "method": "isSupervisable",
  "data": {
    "items": [
      {"port": 0, "input": true, "output": false},
      {"port": 1, "input": true, "output": false}
    ]
  }
}

5) Get information on which states that can be supervised:

{
  "apiVersion": "2.0",
  "method": "getSupportedStates",
  "params": [
    { "port": 1 }
  ]
}

6) Parse the JSON response. The response presents information on which states that can be supervised.

{
  "apiVersion": "2.0",
  "method": "getSupportedStates",
  "data": {
    "items": [
      {
        "port": 1,
        "states": [
          {"name": "short"},
          {"name": "close"},
          {"name": "open"},
          {"name": "cut"}
        ]
      }
    ]
  }
}

7) Set the ranges for each supported state, and the ports as supervised.

{
  "apiVersion": "2.0",
  "method": "setSupervised",
  "params": [
    {
      "port": 0,
      "supervised": true,
      "ranges": [
        {
          "state": "short",
          "lowerlimit": 0,
          "upperlimit": 9
        },
        {
          "state": "close",
          "lowerlimit": 10,
          "upperlimit": 90
        },
        {
          "state": "open",
          "lowerlimit": 91,
          "upperlimit": 200
        },
        {
          "state": "cut",
          "lowerlimit": 201,
          "upperlimit": 255
        }
      ]
    },
    {
      "port": 1,
      "supervised": true,
      "ranges": [
        {
          "state": "short",
          "lowerlimit": 0,
          "upperlimit": 9
        },
        {
          "state": "close",
          "lowerlimit": 10,
          "upperlimit": 90
        },
        {
          "state": "open",
          "lowerlimit": 91,
          "upperlimit": 200
        },
        {
          "state": "cut",
          "lowerlimit": 201,
          "upperlimit": 255
        }
      ]
    }
  ]
}

8) Read the response to see if the operation was successful.

{
  "apiVersion": "2.0",
  "method": "setSupervised",
  "data": {
    "items": [
      {"port": 0, "code": 1, "message": ""},
      {"port": 1, "code": 1, "message": ""}
    ]
  }
}

For a list of potential errors, see General error codes.

Read status from supervised ports

Use this example to check the analog level of a supervised port and the state that it corresponds to.

1) Read the current state and level of a supervised port:

http://myserver/axis-cgi/supervisedio.cgi

JSON request example

{
  "apiVersion": "2.0",
  "method": "getSupervised",
  "params": [
    { "port": 1 },
    { "port": 2 }
  ]
}

2) Parse the JSON response. The response presents information about the current state of the ports.

{
  "apiVersion": "2.0",
  "method": "getSupervised",
  "data": {
    "items": [
      {
        "port": 1,
        "supervised": true,
        "supervisable": true,
        "state": "short",
        "level": 0
      },
      {
        "port": 2,
        "supervised": true,
        "supervisable": true,
        "state": "open",
        "level": 2300
      }
    ]
  }
}

For a list of potential errors, see General error codes.

Get supported versions

Use this example to check if the device supports a feature before you use it.

1) Get a list of supported JSON API versions. Note that no apiVersion is supposed to be defined in the request.

http://myserver/axis-cgi/supervisedio.cgi

JSON request example

{
  "method": "getSupportedVersions",
  "context": "123"
}

2) Parse the JSON response to determine if the operation succeeded.

a) Successful response

{
  "apiVersion": "2.0",
  "method": "getSupportedVersions",
  "context": "123",
  "data": {
    "apiVersions": [
      "1.0",
      "2.0"
    ]
  }
}

b) Error response

For a list of potential errors, see General error codes.

See getSupportedVersions for further instructions.

API specification

getNumberOfPorts

This CGI method is used to return the number of input and output ports.

Request

Security level: Operator
Method: POST

http://<myserver>/axis-cgi/supervisedio.cgi

Request body syntax

{
  "apiVersion": <string>,
  "method": "getNumberOfPorts",
  "context": <string>
}

Parameter	Description
`apiVersion=<string>`	Current version of the API.
`method=getNumberOfPorts`	The method described in this section.
`context=<string>`	Text string echoed back in the response (optional).

Return value - Success

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

Response body syntax

{
  "apiVersion": <string>,
  "method": "getNumberOfPorts",
  "context": <string>,
  "data": {
    "inputs": <integer>,
    "outputs": <integer>
  }
}

Parameter	Description
`apiVersion=<string>`	The current version of the API.
`method="getNumberOfPorts"`	The method described in this section.
`context=<string>`	A text string echoed back if it was provided by the client in the corresponding request.
`data.inputs`	Number of input ports.
`data.outputs`	Number of output ports.

Return value - Error

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

Response body syntax

{
  "apiVersion": <string>,
  "method": "getNumberOfPorts",
  "context": <string>,
  "error": {
    "code": <integer>,
    "message": <string>
  }
}

Parameter	Description
`apiVersion=<string>`	The current API version.
`method="getNumberOfPorts"`	The method described in this section.
`context=<string>`	The text string from the request echoed back in the response.
`error.code`	One of the error codes listed in General error codes.
`error.message`	One of the error messages listed in General error codes.

isSupervisable

This CGI method is used to check if an I/O port can be set to supervised.

Request

Security level: Operator
Method: POST

http://<myserver>/axis-cgi/supervisedio.cgi

Request body syntax

{
  "apiVersion": <string>,
  "method": "isSupervisable",
  "context": <string>,
  "params": [
    {"port": <integer>}
  ]
}

Parameter	Description
`apiVersion=<string>`	The current API version.
`method=isSupervisable`	The method described in this section.
`context=<string>`	Text string echoed back in the response (optional).
`params[].port=<integer>`	This integer specify which I/O port to check. If left out, only supervisable ports are returned (optional).

Return value - Success

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

Response body syntax

{
  "apiVersion": <string>,
  "method": "isSupervisable",
  "context": <string>,
  "data": {
    "items": [
      {"port": <integer>, "input": <boolean>, "output": <boolean>}
    ]
  }
}

Parameter	Description
`apiVersion=<string>`	The current API version.
`method="isSupervisable"`	The method described in this section.
`context=<string>`	A text string echoed back if it was provided by the client in the corresponding request.
`data.items[].port`	The port number.
`data.items[].input`	True if supervised input exists, false if not.
`data.items[].output`	True if supervised output exists, false if not.

Return value - Error

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

Response body syntax

{
  "apiVersion": <string>,
  "method": "isSupervisable",
  "context": <string>,
  "error": {
    "code": <integer>,
    "message": <string>
  }
}

Parameter	Description
`apiVersion=<string>`	The current API version.
`method="isSupervisable"`	The method described in this section.
`context=<string>`	The text string from the request echoed back in the response.
`error.code`	One of the error codes listed in General error codes.
`error.message`	One of the error messages listed in General error codes.

getSupervised

This CGI method is used to check if an I/O port is supervised and its current state.

Request

Security level: Operator
Method: POST

http://<myserver>/axis-cgi/supervisedio.cgi

Request body syntax

{
  "apiVersion": <string>,
  "method": "getSupervised",
  "context": <string>,
  "params": [
    {"port": <integer>}
  ]
}

Parameter	Description
`apiVersion=<string>`	The current version of the API.
`method=getSupervised`	The method described in this section.
`context=<string>`	Text string echoed back in the response (optional).
`params[].port=<integer>`	This integer specify which I/O port to check. If left out, information regarding all ports are returned (optional).

Return value - Success

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

Response body syntax

{
  "apiVersion": <string>,
  "method": "getSupervised",
  "context": <string>,
  "data": {
    "items": [
      {
        "port": <integer>,
        "supervised": <boolean>,
        "supervisable": <boolean>,
        "state": <string>,
        "level": <integer>
      }
    ]
  }
}

Parameter	Description
`apiVersion=<string>`	The current version of the API.
`method="getSupervised"`	The method described in this section.
`context=<string>`	A text string echoed back if it was provided by the client in the corresponding request.
`data.items[].port`	Port number.
`data.items[].supervised`	True if supervised, false if not.
`data.items[]supervisable`	True if supervisable, false if not.
`data.items[].state`	The state of the port.
`data.items[].level`	The current analog level.

Return value - Error

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

Response body syntax

{
  "apiVersion": <string>,
  "method": "getSupervised",
  "context": <string>,
  "error": {
    "code": <integer>,
    "message": <string>
  }
}

Parameter	Description
`apiVersion=<string>`	The current version of the API.
`method="getSupervised"`	The method described in this section.
`context=<string>`	The text string from the request echoed back in the response.
`error.code`	One of the error codes listed in General error codes.
`error.message`	One of the error messages listed in General error codes.

setSupervised

This CGI method is used to enable/disable supervision of an I/O port, or configure the ranges for a supervised port.

Request

Security level: Operator
Method: POST

http://<myserver>/axis-cgi/supervisedio.cgi

Request body syntax

{
  "apiVersion": <string>,
  "method": "setSupervised",
  "context": <string>,
  "params": [
    {
      "port": <integer>,
      "supervised": <boolean>,
      "ranges": [
        {
          "state": <string>,
          "lowerlimit": <integer>,
          "upperlimit": <integer>
        }
      ]
    }
  ]
}

Parameter	Description
`apiVersion=<string>`	The current version of the API.
`method=setSupervised`	The method described in this section.
`context=<string>`	Text string echoed back in the response (optional).
`params[].port<integer>`	The port to configure. If omitted, all ports are configured.
`params[].supervised=<boolean>`	`True` activates supervised I/O for the port. `False` deactivates supervised I/O for the port.
`params[].ranges[]`	Array with range of limits set for each state (optional).
`params[].ranges[].state`	The state to set the ranges for.
`params[].ranges[].lowerlimit`	The lower limit.
`params[].ranges[].upperlimit`	The upper limit.

Return value - Success

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

Response body syntax

{
  "apiVersion": <string>,
  "method": "setSupervised",
  "context": <string>,
  "data": {
    "items": [
      {"port": <integer>, "code": <integer>, "message": <string>}
    ]
  }
}

Parameter	Description
`apiVersion=<string>`	The current version of the API.
`method="setSupervised"`	The method described in this section.
`context=<string>`	A text string echoed back if it was provided by the client in the corresponding request.
`data.items[].port`	Port number.
`data.items[].code`	`1` if the operation was successful. If the operation failed, one of the error codes listed in Errors will be listed instead.
`data.items[].message`	A string describing the error.

Return value - Error

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

Response body syntax

{
  "apiVersion": <string>,
  "method": "setSupervised",
  "context": <string>,
  "error": {
    "code": <integer>,
    "message": <string>
  }
}

Parameter	Description
`apiVersion=<string>`	The current version of the API.
`method="setSupervised"`	The method described in this section.
`context=<string>`	The text string from the request echoed back in the response.
`error.code`	One of the error codes listed in General error codes.
`error.message`	One of the error messages listed in General error codes.

getSupervisedRanges

This CGI method is used to get the ranges that is corresponding to the states of a port.

Request

Security level: Operator
Method: POST

http://<myserver>/axis-cgi/supervisedio.cgi

Request body syntax

{
  "apiVersion": <string>,
  "method": "getSupervisedRanges",
  "context": <string>,
  "params": [
    {"port": <integer>}
  ]
}

Parameter	Description
`apiVersion=<string>`	The current version of the API.
`method=getSupervisedRanges`	The method described in this section.
`context=<string>`	Text string echoed back in the response (optional).
`params[].port=<integer>`	This integer state which I/O port to check. If it is omitted, information about all ports are returned (optional).

Return value - Success

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

Response body syntax

{
  "apiVersion": <string>,
  "method": "getSupervisedRanges",
  "context": <string>,
  "data": {
    "items": [
      {
        "port": <integer>,
        "ranges": [
          {
            "state": <string>,
            "lowerlimit": <integer>,
            "upperlimit": <integer>
          }
        ]
      }
    ]
  }
}

Parameter	Description
`apiVersion=<string>`	The current version of the API.
`method="getSupervisedRanges"`	The method described in this section.
`context=<string>`	A text string echoed back if it was provided by the client in the corresponding request.
`data.items[].port`	The port number.
`data.items[].ranges[]`	Array holding information about the ranges. If the ranges are not set, or the port is not supervisable, the array is empty.
`data.items[].ranges[].state`	The name of the state.
`data.items[].ranges[].lowerlimit`	Lower voltage range.
`data.items[].ranges[].upperlimit`	Upper voltage range.

Return value - Error

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

Response body syntax

{
  "apiVersion": <string>,
  "method": "getSupervisedRanges",
  "context": <string>,
  "error": {
    "code": <integer>,
    "message": <string>
  }
}

Parameter	Description
`apiVersion=<string>`	The current version of the API.
`method="getSupervisedRanges"`	The method described in this section.
`context=<string>`	The text string from the request echoed back in the response.
`error.code`	One of the error codes listed in General error codes.
`error.message`	One of the error messages listed in General error codes.

getSupportedStates

This CGI method is used to retrieve a list of the states supported by the API.

Request

Security level: Operator
Method: POST

http://<myserver>/axis-cgi/supervisedio.cgi

Request body syntax

{
  "apiVersion": <string>,
  "method": "getSupportedStates",
  "context": <string>,
  "params": [
    {"port": <integer>}
  ]
}

Parameter	Description
`apiVersion=<string>`	The current version of the API.
`method=getSupportedStates`	The method described in this section.
`context=<string>`	Text string echoed back in the response (optional).
`params[].port=<integer>`	This integer specify which I/O port to check. If omitted, information regarding all ports is returned (optional).

Return value - Success

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

Response body syntax

{
  "apiVersion": <string>,
  "method": "getSupportedStates",
  "context": <string>,
  "data": {
    "items": [
      {
        "port": <integer>,
        "states": [
          {"name": <string>}
        ]
      }
    ]
  }
}

Parameter	Description
`apiVersion=<string>`	The current version of the API.
`method=getSupportedStates`	The method the response corresponds to.
`context=<string>`	A text string echoed back if it was provided by the client in the corresponding request.
`data.items[].port`	The port number.
`data.items[].states[].name`	Name of the state.

Return value - Error

Response body syntax

{
  "apiVersion": <string>,
  "method": "getSupportedStates",
  "context": <string>,
  "error": {
    "code": <integer>,
    "message": <string>
  }
}

Parameter	Description
`apiVersion=<string>`	The current version of the API.
`method=getSupportedStates`	The method the response corresponds to.
`context=<string>`	The text string from the request echoed back in the response.
`error.code`	One of the error codes listed in General error codes.
`error.message`	One of the error messages listed in General error codes.

getSupportedVersions

This CGI method is used to retrieve a list of the supported response schema versions that are available.

Request

Security level: Operator
Method: POST

http://<myserver>/axis-cgi/supervisedio.cgi

Request body syntax

{
  "method": "getSupportedVersions",
  "context": <string>
}

Parameter	Description
`method="getSupportedVersions"`	Specifies that the `getSupportedVersions` operation is performed.
`context=<string>`	Text string echoed back in the response (optional).

Return value - Success

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

Response body syntax

{
  "method": "getSupportedVersions",
  "context": <string>,
  "data": {
    "apiVersions": ["<Major1>.<Minor1>", "<Major2>.Minor2"]
  }
}

Parameter	Description
`method="getSupportedVersions"`	The method described in this section.
`context=<string>`	A text string echoed back if it was provided by the client in the corresponding request.
`data.apiVersions[]=<list of versions>`	List of supported versions, all major versions with the highest supported minor version.
`<list of versions>`	List of “<Major>.<Minor>” versions, e.g. [“1.0”, “2.0”].

Return value - Error

HTTP code: 200 OK
Content-type: application/json

Response body syntax

{
  "method": "getSupportedVersions",
  "context": <string>,
  "error": {
    "code": <integer>,
    "message": <string>
}

Parameter	Description
`method=<string>`	The method name.
`context=<string>`	The text string from the request echoed back in the response.
`error.code`	One of the error codes listed in General error codes.
`error.message`	One of the error messages listed in General error codes.

General error codes

General error codes for API version 1.0
Error code	Description
`100`	Unsupported API version
`101`	Internal error
`102`	Mandatory parameter(s) missing
`103`	Unknown parameter supplied
`200`	JSON input error
`201`	Unexpected error
`202`	Generic error
`203`	Invalid method
`300`	Faulty parameter
`301`	Invalid range
`302`	Invalid port parameter
`303`	Port not supervisable

General error codes for API version 2.0
Error code	Description
`1100`	Internal error
`2100`	Unsupported API version
`2101`	JSON input error
`2102`	Invalid method
`2103`	Mandatory parameter(s) missing
`2200`	Unknown parameter supplied
`2201`	Unexpected error
`2202`	Generic error
`2203`	Faulty parameter value
`2204`	Invalid range
`2205`	Invalid port parameter
`2206`	Port not supervisable