Skip to main content

Light control

Light control API

The VAPIX® Light control API makes it possible to control the behavior and functionality of IR and White light LEDs in the Axis devices. This is done through JSON commands, and the API also have support for the On-screen controls API in order to control the lights directly, something that was not possible with the older Light control service API.

Overview

The API is built around the lightcontrol.cgi, which makes it possible to query for one or several light devices and their status, controlling their light intensity and focus, and turning them on/off.

The CGI consists of the following methods:

MethodDescription
getSupportedVersionsLists the API versions that are supported by the CGI.
getServiceCapabilitiesLists the capabilities of the light control.
getLightInformationLists the light control information.
activateLightActivates the light.
deactivateLightDeactivates the light.
enableLightEnables the light functionality on the device.
disableLightDisables the light functionality on the device.
getLightStatusRetrieves the light status from a given Light ID.
setAutomaticIntensityModeEnables the automatic light intensity control.
getValidIntensityLists the valid light intensity values.
setManualIntensityManually sets the intensity.
getManualIntensityRetrieves the intensity from the setManualIntensity request.
setIndividualIntensityManually sets the intensity for an individual LED.
getIndividualIntensityRetrieves the intensity from the setIndividualIntensity request.
getCurrentIntensityRetrieves the current intensity.
setAutomaticAngleOfIlluminationModeAutomatically controls the angle of illumination. Using this mode means that the angle of illumination is the same as the camera’s angle of view.
getValidAngleOfIlluminationLists the valid angle of illumination values.
setManualAngleOfIlluminationSets the manual angle of illumination. This is useful when the angle of illumination needs to be different from the camera’s view angle.
getManualAngleOfIlluminationRetrieves the angle of illumination from the setManualAngleOfIllumination request.
getCurrentAngleOfIlluminationRetrieves the current angle of illumination.
setLightSynchronizeDayNightModeEnables automatic synchronization with the day/night mode.
getLightSynchronizeDayNightModeChecks if the automatic synchronization is enabled with the day/night mode.
getValidIRWavelengthsLists the valid IR wavelengths.
setIRWavelengthSets the IR wavelength.
getIRWavelengthRetrieves the currently set IR wavelength

Identification

  • Property: Properties.API.HTTP.Version=3
  • Property: Properties.LightControl.LightControl2=yes
  • Firmware: 7.40 and later
  • API Discovery: id=light-control

Obsoletes

A successful response from the getServiceCapabilities method will list supported capabilities of the light controller service. This is followed by an array that contains the supported capabilities for each LEDgroup. It is recommended to use this array, as the global capabilities have been deprecated.

Common examples

Get supported versions

Use this example to get a list of API versions that are supported on the device.

  1. Send a request to receive a list of the supported API versions:
http://myserver/axis-cgi/lightcontrol.cgi

JSON input parameters

{
"context": "my context",
"method": "getSupportedVersions"
}
  1. Parse the JSON response.

a) Successful response example:

{
"apiVersion": "2.1",
"context": "my context",
"method": "getSupportedVersions",
"data": {
"apiVersions": [
"1.0",
"2.1",
]
}
}

b) Failed response example:

{
"apiVersion": "2.1",
"context": "my context",
"method": "getSupportedVersions",
"error": {
"code": 8000,
"message": "Internal error, could not complete request."
}
}

See getSupportedVersions for further instructions.

Get service capabilities

Use this example to list the capabilities of the light controller that is supported on the device.

Please note that the global capabilities have been deprecated and the capabilities array should be used instead.

  1. Send a request to receive a list showing the light service capabilities.
http://myserver/axis-cgi/lightcontrol.cgi

JSON input parameters

{
"apiVersion": "1.0",
"context": "my context",
"method": "getServiceCapabilities"
}
  1. Parse the JSON response.

a) Successful response example:

{
"apiVersion": "1.0",
"context": "my context",
"method": "getServiceCapabilities",
"data": {
"automaticIntensitySupport": true,
"manualIntensitySupport": true,
"individualIntensitySupport": false,
"getCurrentIntensitySupport": true,
"manualAngleOfIlluminationSupport": false,
"automaticAngleOfIlluminationSupport": false,
"dayNightSynchronizeSupport": true,
"multiIRWaveLengthSupport": true,
"capabilities": [
{
"lightID": id,
"automaticIntensitySupport": true,
"manualIntensitySupport": true,
"individualIntensitySupport": false,
"getCurrentIntensitySupport": true,
"manualAngleOfIlluminationSupport": false,
"automaticAngleOfIlluminationSupport": false,
"dayNightSynchronizeSupport": true,
"multiIRWaveLengthSupport": true
},
{
"lightID": id,
"automaticIntensitySupport": true,
"manualIntensitySupport": true,
"individualIntensitySupport": false,
"getCurrentIntensitySupport": true,
"manualAngleOfIlluminationSupport": false,
"automaticAngleOfIlluminationSupport": false,
"dayNightSynchronizeSupport": true,
"multiIRWaveLengthSupport": true
}
]
}
}

b) Failed response example:

{
"apiVersion": "1.0",
"context": "my context",
"method": "getServiceCapabilities",
"error": {
"code": 7000,
"message": "The requested API version is not supported by this implementation."
}
}

See getServiceCapabilities for further instructions.

Get light information

Use this example to list the light control information on the device.

  1. Send a request to receive a list of lights and their configuration and status.
http://myserver/axis-cgi/lightcontrol.cgi

JSON input parameters

{
"apiVersion": "1.0",
"context": "my context",
"method": "getLightInformation",
"params": {
}
}
  1. Parse the JSON response.

a) Successful response example:

{
"apiVersion": "1.0",
"context": "my context",
"method": "getLightInformation",
"data": {
"items": [
{
"lightID": "led0",
"lightType": "IR",
"enabled": true,
"synchronizeDayNightMode": true,
"lightState": false,
"automaticIntensityMode": false,
"automaticAngleOfIlluminationMode": false,
"nrOfLEDs": 1,
"error": false,
"errorInfo": ""
},
{
"lightID": "led1",
"lightType": "IR",
"enabled": true,
"synchronizeDayNightMode": false,
"lightState": false,
"automaticIntensityMode": false,
"automaticAngleOfIlluminationMode": false,
"nrOfLEDs": 2,
"error": false,
"errorInfo": ""
}
]
}
}

b) Failed response example:

{
"apiVersion": "1.0",
"context": "my context",
"method": "getLightInformation",
"error": {
"code": 2000,
"message": "Failed to allocate memory for request."
}
}

See getLightInformation for further instructions.

Activate light

Use this example to turn on the light of a specific Light ID.

  1. Send a request to activate the lights of a given Light ID. Please note that a single Light ID can still contain several LEDs and/or lamps.
http://myserver/axis-cgi/lightcontrol.cgi

JSON input parameters

{
"apiVersion": "1.0",
"context": "my context",
"method": "activateLight",
"params": {
"lightID": "led0"
}
}
  1. Parse the JSON response.

a) Successful response example:

{
"apiVersion": "1.0",
"context": "my context",
"method": "activateLight",
"data": {
}
}

b) Failed response example:

{
"apiVersion": "1.0",
"context": "my context",
"method": "activateLight",
"error": {
"code": 1002,
"message": "Provided lightID parameter is not valid for the device."
}
}

See activateLight for further instructions.

Deactivate light

Use this example to turn off the lights of a specific Light ID.

  1. Send a request to deactivate the lights of a given Light ID.
http://myserver/axis-cgi/lightcontrol.cgi

JSON input parameters

{
"apiVersion": "1.0",
"context": "my context",
"method": "deactivateLight",
"params": {
"lightID": "led0",
}
}
  1. Parse the JSON response.

a) Successful response example:

{
"apiVersion": "1.0",
"context": "my context",
"method": "deactivateLight",
"data": {
}
}

b) Failed response example:

{
"apiVersion": "1.0",
"context": "my context",
"method": "deactivateLight",
"error": {
"code": 1002,
"message": "Provided lightID parameter is not valid for the device."
}
}

See deactivateLight for further instructions.

Enable light

Use this example to enable the lights of a specific Light ID. Note that a disabled light can not be turned on.

  1. Send a request to enable the lights of a given Light ID.
http://myserver/axis-cgi/lightcontrol.cgi

JSON input parameters

{
"apiVersion": "1.0",
"context": "my context",
"method": "enableLight",
"params": {
"lightID": "led0",
}
}
  1. Parse the JSON response.

a) Successful response example:

{
"apiVersion": "1.0",
"context": "my context",
"method": "enableLight",
"data": {
}
}

b) Failed response example:

{
"apiVersion": "1.0",
"context": "my context",
"method": "enableLight",
"error": {
"code": 1005,
"message": "Hardware failure, could not complete request."
}
}

See enableLight for further instructions.

Disable light

Use this example to disable the light of a specific Light ID. Note that a disabled light can not be turned on.

  1. Send a request to disable the lights of a given Light ID.
http://myserver/axis-cgi/lightcontrol.cgi

JSON input parameters

{
"apiVersion": "1.0",
"context": "my context",
"method": "disableLight",
"params": {
"lightID": "led0",
}
}
  1. Parse the JSON response.

a) Successful response example:

{
"apiVersion": "1.0",
"context": "my context",
"method": "disableLight",
"data": {
}
}

b) Failed response example:

{
"apiVersion": "1.0",
"context": "my context",
"method": "disableLight",
"error": {
"code": 1005,
"message": "Hardware failure, could not complete request."
}
}

See disableLight for further instructions.

Get light status

Use this example to get the status of a specified Light ID.

  1. Send a request to receive the status of the lights of a given Light ID.
http://myserver/axis-cgi/lightcontrol.cgi

JSON input parameters

{
"apiVersion": "1.0",
"context": "my context",
"method": "getLightStatus",
"params": {
"lightID": "led0"
}
}
  1. Parse the JSON response.

a) Successful response example:

{
"apiVersion": "1.0",
"context": "my context",
"method": "getLightStatus",
"data": {
"status": true
}
}

b) Failed response example:

{
"apiVersion": "1.0",
"context": "my context",
"method": "getLightStatus",
"error": {
"code": 1002,
"message": "Provided lightID parameter is not valid for the device."
}
}

See getLightStatus for further instructions.

Set automatic intensity mode

Use this example to enable the automatic light intensity controller.

  1. Send a request to change the setting of the automatic intensity mode.
http://myserver/axis-cgi/lightcontrol.cgi

JSON input parameters

{
"apiVersion": "1.0",
"context": "my context",
"method": "setAutomaticIntensityMode",
"params": {
"lightID": "led0",
"enabled": true
}
}
  1. Parse the JSON response.

a) Successful response example:

{
"apiVersion": "1.0",
"context": "my context",
"method": "setAutomaticIntensityMode",
"data": {
}
}

b) Failed response example:

{
"apiVersion": "1.0",
"context": "my context",
"method": "setAutomaticIntensityMode",
"error": {
"code": 1005,
"message": "Hardware failure, could not complete request."
}
}

See setAutomaticIntensityMode for further instructions.

Get valid intensity

Use this example to get a list of valid light intensity ranges. Values within this range can be used to change the intensity of the light when using the setManualIntensity method.

  1. Send a request to receive a list of supported intensity ranges.
http://myserver/axis-cgi/lightcontrol.cgi

JSON input parameters

{
"apiVersion": "1.0",
"context": "my context",
"method": "getValidIntensity",
"params": {
"lightID": "led0",
}
}
  1. Parse the JSON response.

a) Successful response example:

{
"apiVersion": "1.0",
"context": "my context",
"method": "getValidIntensity",
"data": {
"ranges": [
{
"low": 0,
"high": 50
}
]
}
}

b) Failed response example:

{
"apiVersion": "1.0",
"context": "my context",
"method": "getValidIntensity",
"error": {
"code": 1002,
"message": "Provided lightID parameter is not valid for the device."
}
}

See getValidIntensity for further instructions.

Set manual intensity

Use this example to set the manual intensity of a light.

  1. Send a request to receive the manual intensity level of a light.
http://myserver/axis-cgi/lightcontrol.cgi

JSON input parameters

{
"apiVersion": "1.0",
"context": "my context",
"method": "setManualIntensity",
"params": {
"lightID": "led0",
"intensity": 50
}
}
  1. Parse the JSON response.

a) Successful response example:

{
"apiVersion": "1.0",
"context": "my context",
"method": "setManualIntensity",
"data": {
}
}

b) Failed response example:

{
"apiVersion": "1.0",
"context": "my context",
"method": "setManualIntensity",
"error": {
"code": 1002,
"message": "Provided lightID parameter is not valid for the device."
}
}

See setManualIntensity for further instructions.

Get manual intensity

Use this example to get the manually configured intensity from the previous example.

  1. Send a request to receive a response with the currently configured manual intensity level of a light.
http://myserver/axis-cgi/lightcontrol.cgi

JSON input parameters

{
"apiVersion": "1.0",
"context": "my context",
"method": "getManualIntensity",
"params": {
"lightID": "led0"
}
}
  1. Parse the JSON response.

a) Successful response example:

{
"apiVersion": "1.0",
"context": "my context",
"method": "getManualIntensity",
"data": {
"intensity": 50
}
}

b) Failed response example:

{
"apiVersion": "1.0",
"context": "my context",
"method": "getManualIntensity",
"error": {
"code": 1002,
"message": "Provided lightID parameter is not valid for the device."
}
}

See getManualIntensity for further instructions.

Set individual intensity

Use this example to manually change the intensity of an individual LED light.

  1. Send a request to receive a manual intensity level for either a single or group of LED lights.
http://myserver/axis-cgi/lightcontrol.cgi

JSON input parameters

{
"apiVersion": "1.0",
"context": "my context",
"method": "setIndividualIntensity",
"params": {
"lightID": "led0",
"LEDID": 1,
"intensity": 100
}
}
  1. Parse the JSON response.

a) Successful response example:

{
"apiVersion": "1.0",
"context": "my context",
"method": "setIndividualIntensity",
"data": {
}
}

b) Failed response example:

{
"apiVersion": "1.0",
"context": "my context",
"method": "setIndividualIntensity",
"error": {
"code": 1002,
"message": "Provided lightID parameter is not valid for the device."
}
}

See setIndividualIntensity for further instructions.

Get individual intensity

Use this example to get the manually configured intensity of an individual LED light.

  1. Send a request to receive the current intensity level for either a single or a group of LED lights.
http://myserver/axis-cgi/lightcontrol.cgi

JSON input parameters

{
"apiVersion": "1.0",
"context": "my context",
"method": "getIndividualIntensity",
"params": {
"lightID": "led0",
"LEDID": 2
}
}
  1. Parse the JSON response.

a) Successful response example:

{
"apiVersion": "1.0",
"context": "my context",
"method": "getIndividualIntensity",
"data": {
"intensity": 100
}
}

b) Failed response example:

{
"apiVersion": "1.0",
"context": "my context",
"method": "getIndividualIntensity",
"error": {
"code": 1002,
"message": "Provided lightID parameter is not valid for the device."
}
}

See getIndividualIntensity for further instructions.

Get current intensity

Use this example to get the current intensity of a light.

  1. Send a request to receive the current intensity of a light.
http://myserver/axis-cgi/lightcontrol.cgi

JSON input parameters

{
"apiVersion": "1.0",
"context": "my context",
"method": "getCurrentIntensity",
"params": {
"lightID": "led0"
}
}
  1. Parse the JSON response.

a) Successful response example:

{
"apiVersion": "1.0",
"context": "my context",
"method": "getCurrentIntensity",
"data": {
"intesity": 100
}
}

b) Failed response example:

{
"apiVersion": "1.0",
"context": "my context",
"method": "getCurrentIntensity",
"error": {
"code": 1005,
"message": "Hardware failure, could not complete request."
}
}

See getCurrentIntensity for further instructions.

Set automatic angle of illumination mode

Use this example to automatically control the angle of illumination.

  1. Send a request to receive a change of the automatic angle of illumination mode for a light.
http://myserver/axis-cgi/lightcontrol.cgi

JSON input parameters

{
"apiVersion": "1.0",
"context": "my context",
"method": "setAutomaticAngleOfIlluminationMode",
"params": {
"lightID": "led0",
"enabled": true
}
}
  1. Parse the JSON response.

a) Successful response example:

{
"apiVersion": "1.0",
"context": "my context",
"method": "setAutomaticAngleOfIlluminationMode",
"data": {
}
}

b) Failed response example:

{
"apiVersion": "1.0",
"context": "my context",
"method": "setAutomaticAngleOfIlluminationMode",
"error": {
"code": 1001,
"message": "Method call not supported by the device."
}
}

See setAutomaticAngleOfIlluminationMode for further instructions.

Get valid angle of illumination

Use this example to get a list of supported angle of illumination ranges for a light.

  1. Send a request to receive a list of valid ranges for angle of illumination for a light.
http://myserver/axis-cgi/lightcontrol.cgi

JSON input parameters

{
"apiVersion": "1.0",
"context": "my context",
"method": "getValidAngleOfIllumination",
"params": {
"lightID": "led0"
}
}
  1. Parse the JSON response.

a) Successful response example:

{
"apiVersion": "1.0",
"context": "my context",
"method": "getValidAngleOfIllumination",
"data": {
"ranges": [
{
"low": 10,
"high": 30
},
{
"low": 20,
"high": 50
}
]
}
}

b) Failed response example:

{
"apiVersion": "1.0",
"context": "my context",
"method": "getValidAngleOfIllumination",
"error": {
"code": 1001,
"message": "Method call not supported by the device."
}
}

See getValidAngleOfIllumination for further instructions.

Set manual angle of illumination

Use this example to manually control the angle of illumination.

  1. Send a request to make a change of the manual angle of illumination for a light.
http://myserver/axis-cgi/lightcontrol.cgi

JSON input parameters

{
"apiVersion": "1.0",
"context": "my context",
"method": "setManualAngleOfIllumination",
"params": {
"lightID": "led0",
"angleOfIllumination": 30
}
}
  1. Parse the JSON response.

a) Successful response example:

{
"apiVersion": "1.0",
"context": "my context",
"method": "setManualAngleOfIllumination",
"data": {
}
}

b) Failed response example:

{
"apiVersion": "1.0",
"context": "my context",
"method": "setManualAngleOfIllumination",
"error": {
"code": 1002,
"message": "Provided lightID parameter is not valid for the device."
}
}

See setManualAngleOfIllumination for further instructions.

Get manual angle of illumination

Use this example to get the current configured manual angle of illumination.

  1. Send a request to receive the current configured manual angle of illumination mode for a light.
http://myserver/axis-cgi/lightcontrol.cgi

JSON input parameters

{
"apiVersion": "1.0",
"context": "my context",
"method": "getManualAngleOfIllumination",
"params": {
"lightID": "led0"
}
}
  1. Parse the JSON response.

a) Successful response example:

{
"apiVersion": "1.0",
"context": "my context",
"method": "getManualAngleOfIllumination",
"data": {
"angleOfIllumination": 30
}
}

b) Failed response example:

{
"apiVersion": "1.0",
"context": "my context",
"method": "getManualAngleOfIllumination",
"error": {
"code": 1005,
"message": "Hardware failure, could not complete request."
}
}

See getManualAngleOfIllumination for further instructions.

Get current angle of illumination

Use this example to get the current angle of illumination.

  1. Send a request to receive the current angle of illumination for a light.
http://myserver/axis-cgi/lightcontrol.cgi

JSON input parameters

{
"apiVersion": "1.0",
"context": "my context",
"method": "getCurrentAngleOfIllumination",
"params": {
"lightID": "led0"
}
}
  1. Parse the JSON response.

a) Successful response example:

{
"apiVersion": "1.0",
"context": "my context",
"method": "getCurrentAngleOfIllumination",
"data": {
"angleOfIllumination": 20
}
}

b) Failed response example:

{
"apiVersion": "1.0",
"context": "my context",
"method": "getCurrentAngleOfIllumination",
"error": {
"code": 1001,
"message": "Method call not supported by the device."
}
}

See getCurrentAngleOfIllumination for further instructions.

Set light synchronize day night mode

Use this example to turn on automatic day/night synchronization mode.

  1. Send a request to make a change to the automatic synchronization and day/night mode for a light.
http://myserver/axis-cgi/lightcontrol.cgi

JSON input parameters

{
"apiVersion": "1.0",
"context": "my context",
"method": "setLightSynchronizationDayNightMode",
"params": {
"lightID": "led0",
"enabled": false
}
}
  1. Parse the JSON response.

a) Successful response example:

{
"apiVersion": "1.0",
"context": "my context",
"method": "setLightSynchronizeDayNightMode",
"data": {
}
}

b) Failed response example:

{
"apiVersion": "1.0",
"context": "my context",
"method": "setLightSynchronizeDayNightMode",
"error": {
"code": 1001,
"message": "Method call not supported by the device."
}
}

See setLightSynchronizeDayNightMode for further instructions.

Get light synchronize day night mode

Use this example to check if the automatic synchronization for the day/night mode is enabled.

  1. Send a request to make a change to the automatic synchronization and day/night mode for a light.
http://myserver/axis-cgi/lightcontrol.cgi

JSON input parameters

{
"apiVersion": "1.0",
"context": "my context",
"method": "getLightSynchronizeDayNightMode",
"params": {
"lightID": "led0"
}
}
  1. Parse the JSON response.

a) Successful response example:

{
"apiVersion": "1.0",
"context": "my context",
"method": "getLightSynchronizeDayNightMode",
"data": {
"enabled": false
}
}

b) Failed response exampled:

{
"apiVersion": "1.0",
"context": "my context",
"method": "getLightSynchronizeDayNightMode",
"error": {
"code": 1001,
"message": "Method call not supported by the device."
}
}

See getLightSynchronizeDayNightMode for further instructions.

Get valid infrared wavelengths

Use this example to retrieve a list of valid infrared wavelengths. The wavelengths themselves can be changed with the setIRWavelength method.

  1. Request a list of supported infrared wavelengths.
http://myserver/axis-cgi/lightcontrol.cgi

JSON input parameters

{
"apiVersion": "1.2",
"context": "my context",
"method": "getValidIRWavelengths",
"params": {
"lightID": "led0"
}
}
  1. Parse the JSON response.

a) Successful response example:

{
"apiVersion": "1.2",
"context": "my context",
"method": "getValidIRWavelengths",
"data": {
"wavelength": [
"850nm",
"940nm"
]
}
}

b) Failed response example:

{
"apiVersion": "1.2",
"context": "my context",
"method": "getValidIRWavelengths",
"error": {
"code": 1002,
"message": "Provided lightID parameter is not valid for the device."
}
}

See getValidIRWavelengths for further instructions.

Set infrared wavelength

Use this example to set the infrared wavelength. Changing the wavelength of the will give the light different properties such as different illumination ranges and red glow emissions from the light source.

  1. Request a change of the infrared wavelength.
http://myserver/axis-cgi/lightcontrol.cgi

JSON input parameters

{
"apiVersion": "1.2",
"context": "my context",
"method": "setIRWavelength",
"params": {
"lightID": "led0"
"IRWavelength": wavelength
}
}
  1. Parse the JSON response.

a) Successful response example:

{
"apiVersion": "1.2",
"context": "my context",
"method": "setIRWavelength",
"data": {
}
}

b) Failed response example:

{
"apiVersion": "1.2",
"context": "my context",
"method": "setIRWavelength",
"error": {
"code": 1002,
"message": "Provided lightID parameter is not valid for the device."
}
}

See setIRWavelength for further instructions.

Get infrared wavelength

Use this example to retrieve the currently configured infrared wavelength.

  1. Request a response with the currently configured infrared wavelength.
http://myserver/axis-cgi/lightcontrol.cgi

JSON input parameters

{
"apiVersion": "1.2",
"context": "my context",
"method": "getIRWavelength",
"params": {
"lightID": "led0"
}
}

a) Successful response example:

{
"apiVersion": "1.2",
"context": "my context",
"method": "getIRWavelength",
"data": {
"IRWavelength": wavelength
}
}

b) Failed response example:

{
"apiVersion": "Major.Minor",
"context": "my context",
"method": getIRWavelength",
"error": {
"code": 1002,
"message": "Provided lightID parameter is not valid for the device."
}
}

See getIRWavelength for further instructions.

API specification

getSupportedVersions

A CGI method used to retrieve supported API versions. The returning list consists of the supported major versions as well as the highest supported minor versions. Please note that the version is for the API as a whole, i.e. for all methods in the CGI.

Request

  • Security level: admin, operator
  • Method: POST
http://myserver/axis-cgi/lightcontrol.cgi

Request body syntax

{
"apiVersion": <major>.<minor>,
"context": <string>,
"method": "getSupportedVersions",
"params": {}
}

getSupportedVersions request parameters

ParameterTypeDescription
apiVersionStringThe API version that should be used.
contextStringThe client sets this value and the CGI will echo this context string back in the response (optional).
methodStringThe performed operation.
paramsJSON objectContainer for the method specific parameters.

Return value - Success

Returns an array containing the supported API versions.

  • HTTP Code: 200 OK
  • Content-Type: application/json

Response body syntax

{
"apiVersion": "Major.Minor",
"context": "Echoed if provided by the client in the corresponding request",
"method": "getSupportedVersions",
"data": {
"apiVersions": ["<Major1>.<Minor1>", "<Major2>.<Minor2>"]
}
}

getSupportedVersions response parameters

ParameterTypeDescription
apiVersionStringThe API version that should be used.
contextStringThe client sets this value and the CGI will echo this context string back in the response (optional).
methodStringThe performed operation.
dataJSON objectContainer for the response specific parameters.
apiVersionsArrayShows the supported API versions.

Return value - Failure

  • HTTP Code: 200 OK
  • Content-Type: application/json

Response body syntax

{
"apiVersion": "Major.Minor",
"context": "Echoed if provided by the client in the corresponding request",
"method": "The called method",
"error": {
"code": integer error code,
"message": "Error message"
}
}

Error codes

There are no specific error codes for this method. General errors are listed in General error codes.

getServiceCapabilities

A CGI method that lists the light service capabilities.

Please note that the global capabilities have been deprecated and the capabilities array should be used instead.

Request

  • Security level: admin, operator
  • Method: POST
http://myserver/axis-cgi/lightcontrol.cgi

Request body syntax

{
"apiVersion": <major>.<minor>,
"context": <string>,
"method": "getServiceCapabilities",
"params": {}
}

getServiceCapabilities request parameters

ParameterTypeDescription
apiVersionStringThe API version that should be used.
contextStringThe client sets this value and the CGI will echo this context string back in the response (optional).
methodStringThe performed operation.
paramsJSON objectContainer for the method specific parameters.

Return value - Success

  • HTTP Code: 200 OK
  • Content-Type: application/json

Response body syntax

{
"apiVersion": "Major.Minor",
"context": "Echoed if provided by the client in the corresponding request",
"method": "getServiceCapabilities",
"data": {
"automaticIntensitySupport": true | false,
"manualIntensitySupport": true | false,
"individualIntensitySupport": true | false,
"getCurrentIntensitySupport": true | false,
"manualAngleOfIlluminationSupport": true | false,
"automaticAngleOfIlluminationSupport": true | false,
"dayNightSynchronizeSupport": true | false,
"multiIRWaveLengthSupport": true | false,
"capabilities": [
{
"lightID": id,
"automaticIntensitySupport": true | false,
"manualIntensitySupport": true | false,
"individualIntensitySupport": true | false,
"getCurrentIntensitySupport": true | false,
"manualAngleOfIlluminationSupport": true | false,
"automaticAngleOfIlluminationSupport": true | false,
"dayNightSynchronizeSupport": true | false,
"multiIRWaveLengthSupport": true | false
},
{
"lightID": id,
"automaticIntensitySupport": true | false,
"manualIntensitySupport": true | false,
"individualIntensitySupport": true | false,
"getCurrentIntensitySupport": true | false,
"manualAngleOfIlluminationSupport": true | false,
"automaticAngleOfIlluminationSupport": true | false,
"dayNightSynchronizeSupport": true | false,
"multiIRWaveLengthSupport": true | false
}
]
}
}

getServiceCapabilities response parameters

ParameterTypeDescription
apiVersionStringThe API version that should be used.
contextStringThe client sets this value and the CGI will echo this context string back in the response (optional).
methodStringThe performed operation.
dataJSON objectContainer for the response specific parameters.
automaticIntensitySupportBooleanIndicates that setAutomaticIntensityMode is supported.
manualIntensitySupportBooleanIndicates that getManualIntensity and setManualIntensity are supported.
individualIntensitySupportBooleanIndicates that getIndividualIntensity and setIndividualIntensity are supported.
getCurrentIntensitySupportBooleanIndicates that getCurrentIntensity is supported.
manualAngleOfIlluminationsupportBooleanIndicates that setManualAngleOfIllumination is supported.
automaticAngleOfIlluminationSupportBooleanIndicates that setAutomaticAngleOfIlluminationMode is supported.
dayNightSynchronizeSupportBooleanIndicates that setLightSynchronizeDayNightMode is supported.
multiIRWaveLengthSupportBooleanIndicates that getValidIRWavelengths, setIRWavelength and getIRWavelength are supported.
capabilitiesJSON objectContainer for supported capabilities for each LEDgroup.
lightIDStringThe ID of the LEDgroup.

Return value - Failure

  • HTTP Code: 200 OK
  • Content-Type: application/json

Response body syntax

{
"apiVersion": "Major.Minor",
"context": "Echoed if provided by the client in the corresponding request",
"method": "The called method",
"error": {
"code": integer error code,
"message": "Error message"
}
}

Error codes

There are no specific error codes for this method. General errors are listed in General error codes.

getLightInformation

A CGI method that lists the light control information.

Request

  • Security level: admin, operator
  • Method: POST
http://myserver/axis-cgi/lightcontrol.cgi

Request body syntax

{
"apiVersion": <major>.<minor>,
"context": <string>,
"method": "getLightInformation",
"params": {}
}

getLightInformation request parameters

ParameterTypeDescription
apiVersionStringThe API version that should be used.
contextStringThe client sets this value and the CGI will echo this context string back in the response (optional).
methodStringThe performed operation.
paramsJSON objectContainer for the method specific parameters.

Return value - Success

Returns an array of lights in the device and their configurations.

  • HTTP Code: 200 OK
  • Content-Type: application/json

Response body syntax

{
"apiVersion": "Major.Minor",
"context": "Echoed if provided by the client in the corresponding request",
"method": "getLightInformation",
"data": {
"items": [
{
"lightID": "id",
"lightType": "type",
"enabled": true | false,
"synchronizeDayNightMode": true | false,
"lightState": true | false,
"automaticIntensityMode": true | false,
"automaticAngleOfIlluminationMode": true | false,
"nrOfLEDs": "numberOfLEDs",
"error": true | false,
"errorInfo": "Error message"
}
]
}
}

getLightInformation response parameters

ParameterTypeDescription
apiVersionStringThe API version that should be used.
contextStringThe client sets this value and the CGI will echo this context string back in the response (optional).
methodStringThe performed operation.
dataJSON objectContainer for the response specific parameters.
lightIDStringUnique ID of the light.
lightTypeStringType identifier of the light.
enabledBooleanIndicates if the light is enabled.
synchronizeDayNightModeBooleanIndicates if the light is synchronized with day/night.
lightStateBooleanIndicates if the light is ON or OFF.
automaticIntensityModeBooleanIndicates if the mode for automatic intensity is active.
automaticAngleOfIlluminationModeBooleanIndicates if the mode for automatic angle of illumination is active.
nrOfLEDsIntegerNumber of configurable LEDs in a light group. The light groups are identified by their Light ID.
errorBooleanAn error has occurred.
errorInfoStringError description.

Return value - Failure

  • HTTP Code: 200 OK
  • Content-Type: application/json

Response body syntax

{
"apiVersion": "Major.Minor",
"context": "Echoed if provided by the client in the corresponding request",
"method": "The called method",
"error": {
"code": integer error code,
"message": "Error message"
}
}

Error codes

CodeDefinitionDescription
1005CARD_MALFUNCTIONING_FAULTCould not find light hardware, could not complete request.
1006WRONG_POE_CLASS_FAULTWrong POE class, could not complete request.

This list contains the error codes for this particular method. For general errors, see General error codes.

activateLight

A CGI method that activates the light.

Request

  • Security level: admin, operator
  • Method: POST
http://myserver/axis-cgi/lightcontrol.cgi

Request body syntax

{
"apiVersion": <major>.<minor>,
"context": <string>,
"method": "activateLight",
"params": {
"lightID": <string>
}
}

activateLight request parameters

ParameterTypeDescription
apiVersionStringThe API version that should be used.
contextStringThe client sets this value and the CGI will echo this context string back in the response (optional).
methodStringThe performed operation.
paramsJSON objectContainer for the method specific parameters.
lightIDStringThe light ID.

Return value - Success

  • HTTP Code: 200 OK
  • Content-Type: application/json

Response body syntax

{
"apiVersion": "Major.Minor",
"context": "Echoed if provided by the client in the corresponding request",
"method": "activateLight",
"data": {
}
}

activateLight response parameters

ParameterTypeDescription
apiVersionStringThe API version that should be used.
contextStringThe client sets this value and the CGI will echo this context string back in the response (optional).
methodStringThe performed operation.
dataJSON objectContainer for the response specific parameters.

Return value - Failure

  • HTTP Code: 200 OK
  • Content-Type: application/json

Response body syntax

{
"apiVersion": "Major.Minor",
"context": "Echoed if provided by the client in the corresponding request",
"method": "The called method",
"error": {
"code": integer error code,
"message": "Error message"
}
}

Error codes

activateLight error codes

CodeDefinitionDescription
1002INVALID_LIGHT_ID_FAULTProvided lightID parameter is not valid for the device.
1005CARD_MALFUNCTIONING_FAULTCould not find light hardware, could not complete request.
1006WRONG_POE_CLASS_FAULTWrong POE class, could not complete request.
1008UPDATE_IRCUTFILTER_FAULTCould not update IR cut filter.
1009LIGHT_DISABLED_FAULTThe light group is turned off and can’t be activated.

This list contains the error codes for this particular method. For general errors, see General error codes.

deactivateLight

A CGI method that deactivates the light.

Request

  • Security level: admin, operator
  • Method: POST
http://myserver/axis-cgi/lightcontrol.cgi

Request body syntax

{
"apiVersion": <major>.<minor>,
"context": <string>,
"method": "deactivateLight",
"params": {
"lightID": <string>
}
}

deactivateLight request parameters

ParameterTypeDescription
apiVersionStringThe API version that should be used.
contextStringThe client sets this value and the CGI will echo this context string back in the response (optional).
methodStringThe performed operation.
paramsJSON objectContainer for the method specific parameters.
lightIDStringThe light ID.

Return value - Success

  • HTTP Code: 200 OK
  • Content-Type: application/json

Response body syntax

{
"apiVersion": "Major.Minor",
"context": "Echoed if provided by the client in the corresponding request",
"method": "deactivateLight",
"data": {
}
}

deactivateLight response parameters

ParameterTypeDescription
apiVersionStringThe API version that should be used.
contextStringThe client sets this value and the CGI will echo this context string back in the response (optional).
methodStringThe performed operation.
dataJSON objectContainer for the response specific parameters.

Return value - Failure

  • HTTP Code: 200 OK
  • Content-Type: application/json

Response body syntax

{
"apiVersion": "Major.Minor",
"context": "Echoed if provided by the client in the corresponding request",
"method": "The called method",
"error": {
"code": integer error code,
"message": "Error message"
}
}

Error codes

deactivateLight error codes

CodeDefinitionDescription
1002INVALID_LIGHT_ID_FAULTProvided lightID parameter is not valid for the device.
1005CARD_MALFUNCTIONING_FAULTCould not find light hardware, could not complete request.
1006WRONG_POE_CLASS_FAULTWrong POE class, could not complete request.

This list contains the error codes for this particular method. For general errors, see General error codes.

enableLight

A CGI method that enables the light functionality.

Request

  • Security level: admin, operator
  • Method: POST
http://myserver/axis-cgi/lightcontrol.cgi

Request body syntax

{
"apiVersion": <major>.<minor>,
"context": <string>,
"method": "enableLight",
"params": {
"lightID": <string>
}
}

enableLight request parameters

ParameterTypeDescription
apiVersionStringThe API version that should be used.
contextStringThe client sets this value and the CGI will echo this context string back in the response (optional).
methodStringThe performed operation.
paramsJSON objectContainer for the method specific parameters.
lightIDStringThe light ID.

Return value - Success

  • HTTP Code: 200 OK
  • Content-Type: application/json

Response body syntax

{
"apiVersion": "Major.Minor",
"context": "Echoed if provided by the client in the corresponding request",
"method": "enableLight",
"data": {
}
}

enableLight response parameters

ParameterTypeDescription
apiVersionStringThe API version that should be used.
contextStringThe client sets this value and the CGI will echo this context string back in the response (optional).
methodStringThe performed operation.
dataJSON objectContainer for the response specific parameters.

Return value - Failure

  • HTTP Code: 200 OK
  • Content-Type: application/json

Response body syntax

{
"apiVersion": "Major.Minor",
"context": "Echoed if provided by the client in the corresponding request",
"method": "The called method",
"error": {
"code": integer error code,
"message": "Error message"
}
}

Error codes

enableLight error codes

CodeDefinitionDescription
1002INVALID_LIGHT_ID_FAULTProvided lightID parameter is not valid for the device.
1005CARD_MALFUNCTIONING_FAULTCould not find light hardware, could not complete request.
1006WRONG_POE_CLASS_FAULTWrong POE class, could not complete request.

This list contains the error codes for this particular method. For general errors, see General error codes.

disableLight

A CGI method that disables the light functionality.

Request

  • Security level: admin, operator
  • Method: POST
http://myserver/axis-cgi/lightcontrol.cgi

Request body syntax

{
"apiVersion": <major>.<minor>,
"context": <string>,
"method": "disableLight",
"params": {
"lightID": <string>
}
}

disableLight request parameters

ParameterTypeDescription
apiVersionStringThe API version that should be used.
contextStringThe client sets this value and the CGI will echo this context string back in the response (optional).
methodStringThe performed operation.
paramsJSON objectContainer for the method specific parameters.
lightIDStringThe light ID.

Return value - Success

  • HTTP Code: 200 OK
  • Content-Type: application/json

Response body syntax

{
"apiVersion": "Major.Minor",
"context": "Echoed if provided by the client in the corresponding request",
"method": "disableLight",
"data": {
}
}

disableLight response parameters

ParameterTypeDescription
apiVersionStringThe API version that should be used.
contextStringThe client sets this value and the CGI will echo this context string back in the response (optional).
methodStringThe performed operation.
dataJSON objectContainer for the response specific parameters.

Return value - Failure

  • HTTP Code: 200 OK
  • Content-Type: application/json

Response body syntax

{
"apiVersion": "Major.Minor",
"context": "Echoed if provided by the client in the corresponding request",
"method": "The called method",
"error": {
"code": integer error code,
"message": "Error message"
}
}

Error codes

disableLight error codes

CodeDefinitionDescription
1002INVALID_LIGHT_ID_FAULTProvided lightID parameter is not valid for the device.
1005CARD_MALFUNCTIONING_FAULTCould not find light hardware, could not complete request.
1006WRONG_POE_CLASS_FAULTWrong POE class, could not complete request.

This list contains the error codes for this particular method. For general errors, see General error codes.

getLightStatus

A CGI method that showcases the light status of a given Light ID.

Request

  • Security level: admin, operator
  • Method: POST
http://myserver/axis-cgi/lightcontrol.cgi

Request body syntax

{
"apiVersion": <major>.<minor>
"context": <string>,
"method": "getLightStatus",
"params": {
"lightID": <string>
}
}

getLightStatus request parameters

ParameterTypeDescription
apiVersionStringThe API version that should be used.
contextStringThe client sets this value and the CGI will echo this context string back in the response (optional).
methodStringThe performed operation.
paramsJSON objectContainer for the method specific parameters.
lightIDStringThe light ID.

Return value - Success

  • HTTP Code: 200 OK
  • Content-Type: application/json

Response body syntax

{
"apiVersion": "Major.Minor",
"context": "Echoed if provided by the client in the corresponding request",
"method": "getLightStatus",
"data": {
"status": true | false
}
}

getLightStatus response parameters

ParameterTypeDescription
apiVersionStringThe API version that should be used.
contextStringThe client sets this value and the CGI will echo this context string back in the response (optional).
methodStringThe performed operation.
dataJSON objectContainer for the response specific parameters.
statusBooleanIndicates if the light is ON or OFF.

Return value - Failure

  • HTTP Code: 200 OK
  • Content-Type: application/json

Response body syntax

{
"apiVersion": "Major.Minor",
"context": "Echoed if provided by the client in the corresponding request",
"method": "The called method",
"error": {
"code": integer error code,
"message": "Error message"
}
}

Error codes

getLightStatus error codes

CodeDefinitionDescription
1002INVALID_LIGHT_ID_FAULTProvided lightID parameter is not valid for the device.
1005CARD_MALFUNCTIONING_FAULTCould not find light hardware, could not complete request.
1006WRONG_POE_CLASS_FAULTWrong POE class, could not complete request.

This list contains the error codes for this particular method. For general errors, see General error codes.

setAutomaticIntensityMode

A CGI method that enables the automatic light intensity control.

Request

  • Security level: admin, operator
  • Method: POST
http://myserver/axis-cgi/lightcontrol.cgi

Request body syntax

{
"apiVersion": <major>.<minor>,
"context": <string>,
"method": "setAutomaticIntensityMode",
"params": {
"lightID": <string>,
"enabled": <boolean>
}
}

setAutomaticIntensityMode request parameters

ParameterTypeDescription
apiVersionStringThe API version that should be used.
contextStringThe client sets this value and the CGI will echo this context string back in the response (optional).
methodStringThe performed operation.
paramsJSON objectContainer for the method specific parameters.
lightIDStringThe light ID.
enabledBooleanEnables automatic light intensity control.

Return value - Success

  • HTTP Code: 200 OK
  • Content-Type: application/json

Response body syntax

{
"apiVersion": "Major.Minor",
"context": "Echoed if provided by the client in the corresponding request",
"method": "setAutomaticIntensityMode",
"data": {
}
}

setAutomaticIntensityMode response parameters

ParameterTypeDescription
apiVersionStringThe API version that should be used.
contextStringThe client sets this value and the CGI will echo this context string back in the response (optional).
methodStringThe performed operation.
dataJSON objectContainer for the response specific parameters.

Return value - Failure

  • HTTP Code: 200 OK
  • Content-Type: application/json

Response body syntax

{
"apiVersion": "Major.Minor",
"context": "Echoed if provided by the client in the corresponding request",
"method": "The called method",
"error": {
"code": integer error code,
"message": "Error message"
}
}

Error codes

setAutomaticIntensityMode error codes

CodeDefinitionDescription
1001NOT_SUPPORTED_FAULTMethod call not supported by the device.
1002INVALID_LIGHT_ID_FAULTProvided lightID parameter is not valid for the device.
1005CARD_MALFUNCTIONING_FAULTCould not find light hardware, could not complete request.
1006WRONG_POE_CLASS_FAULTWrong POE class, could not complete request.

This list contains the error codes for this particular method. For general errors, see General error codes.

getValidIntensity

A CGI method that lists the valid light intensity values.

Request

  • Security level: admin, operator
  • Method: POST
http://myserver/axis-cgi/lightcontrol.cgi

Request body syntax

{
"apiVersion": <major>.<minor>,
"context": <string>,
"method": "getValidIntensity",
"params": {
"lightID": <string>
}
}

getValidIntensity request parameters

ParameterTypeDescription
apiVersionStringThe API version that should be used.
contextStringThe client sets this value and the CGI will echo this context string back in the response (optional).
methodStringThe performed operation.
paramsJSON objectContainer for the method specific parameters.
lightIDStringThe light ID.

Return value - Success

  • HTTP Code: 200 OK
  • Content-Type: application/json

Response body syntax

{
"apiVersion": "Major.Minor",
"context": "Echoed if provided by the client in the corresponding request",
"method": "getValidIntensity",
"data": {
"ranges": [
{
"low": lowerLimit,
"high": upperLimit
}
]
}
}

getValidIntensity response parameters

ParameterTypeDescription
apiVersionStringThe API version that should be used.
contextStringThe client sets this value and the CGI will echo this context string back in the response (optional).
methodStringThe performed operation.
dataJSON objectContainer for the response specific parameters.
rangesArrayArray of the range objects.
lowIntegerThe lower intensity limit for the range.
highIntegerThe upper intensity limit for the range.

Return value - Failure

  • HTTP Code: 200 OK
  • Content-Type: application/json

Response body syntax

{
"apiVersion": "Major.Minor",
"context": "Echoed if provided by the client in the corresponding request",
"method": "The called method",
"error": {
"code": integer error code,
"message": "Error message"
}
}

Error codes

getValidIntensity error codes

CodeDefinitionDescription
1001NOT_SUPPORTED_FAULTMethod call not supported by the device.
1002INVALID_LIGHT_ID_FAULTProvided lightID parameter is not valid for the device.
1005CARD_MALFUNCTIONING_FAULTCould not find light hardware, could not complete request.
1006WRONG_POE_CLASS_FAULTWrong POE class, could not complete request.

This list contains the error codes for this particular method. For general errors, see General error codes.

setManualIntensity

A CGI method that sets the intensity manually.

Request

  • Security level: admin, operator
  • Method: POST
http://myserver/axis-cgi/lightcontrol.cgi

Request body syntax

{
"apiVersion": <major>.<minor>,
"context": <string>,
"method": "setManualIntensity",
"params": {
"lightID": <string>,
"intensity": <integer>
}
}

setManualIntensity request parameters

ParameterTypeDescription
apiVersionStringThe API version that should be used.
contextStringThe client sets this value and the CGI will echo this context string back in the response (optional).
methodStringThe performed operation.
paramsJSON objectContainer for the method specific parameters.
lightIDStringThe light ID.
intensityIntegerThe intensity level of the light.

Return value - Success

  • HTTP Code: 200 OK
  • Content-Type: application/json

Response body syntax

{
"apiVersion": "Major.Minor",
"context": "Echoed if provided by the client in the corresponding request",
"method": "setManualIntensity",
"data": {
}
}

setManualIntensity response parameters

ParameterTypeDescription
apiVersionStringThe API version that should be used.
contextStringThe client sets this value and the CGI will echo this context string back in the response (optional).
methodStringThe performed operation.
dataJSON objectContainer for the response specific parameters.

Return value - Failure

  • HTTP Code: 200 OK
  • Content-Type: application/json

Response body syntax

{
"apiVersion": "Major.Minor",
"context": "Echoed if provided by the client in the corresponding request",
"method": "The called method",
"error": {
"code": integer error code,
"message": "Error message"
}
}

Error codes

setManualIntensity error codes

CodeDefinitionDescription
1001NOT_SUPPORTED_FAULTMethod call not supported by the device.
1002INVALID_LIGHT_ID_FAULTProvided lightID parameter is not valid for the device.
1003INVALID_INTENSITY_FAULTProvided intensity level is out of the supported range.
1005CARD_MALFUNCTIONING_FAULTCould not find light hardware, could not complete request.
1006WRONG_POE_CLASS_FAULTWrong POE class, could not complete request.

This list contains the error codes for this particular method. For general errors, see General error codes.

getManualIntensity

A CGI method that gets the intensity that was sent in the setManualIntensity request.

Request

  • Security level: admin, operator
  • Method: POST
http://myserver/axis-cgi/lightcontrol.cgi

Request body syntax

{
"apiVersion": <major>.<minor>,
"context": <string>,
"method": "getManualIntensity",
"params": {
"lightID": <string>
}
}

getManualIntensity request parameters

ParameterTypeDescription
apiVersionStringThe API version that should be used.
contextStringThe client sets this value and the CGI will echo this context string back in the response (optional).
methodStringThe performed operation.
paramsJSON objectContainer for the method specific parameters.
lightIDStringThe light ID.

Return value - Success

  • HTTP Code: 200 OK
  • Content-Type: application/json

Response body syntax

{
"apiVersion": "Major.Minor",
"context": "Echoed if provided by the client in the corresponding request",
"method": "getManualIntensity",
"data": {
"intensity": manualIntensity
}
}

getManualIntensity response parameters

ParameterTypeDescription
apiVersionStringThe API version that should be used.
contextStringThe client sets this value and the CGI will echo this context string back in the response (optional).
methodStringThe performed operation.
dataJSON objectContainer for the response specific parameters.
intensityIntensityThe currently configured manual intensity.

Return value - Failure

  • HTTP Code: 200 OK
  • Content-Type: application/json

Response body syntax

{
"apiVersion": "Major.Minor",
"context": "Echoed if provided by the client in the corresponding request",
"method": "The called method",
"error": {
"code": integer error code,
"message": "Error message"
}
}

Error codes

getManualIntensity error codes

CodeDefinitionDescription
1001NOT_SUPPORTED_FAULTMethod call not supported by the device.
1002INVALID_LIGHT_ID_FAULTProvided lightID parameter is not valid for the device.
1005CARD_MALFUNCTIONING_FAULTCould not find light hardware, could not complete request.
1006WRONG_POE_CLASS_FAULTWrong POE class, could not complete request.

This list contains the error codes for this particular method. For general errors, see General error codes.

setIndividualIntensity

A CGI method that manually sets the intensity of an individual LED light.

Request

  • Security level: admin, operator
  • Method: POST
http://myserver/axis-cgi/lightcontrol.cgi

Request body syntax

{
"apiVersion": <major>.<minor>,
"context": <string>,
"method": "setIndividualIntensity",
"params": {
"lightID": <string>,
"LEDID": <integer>,
"intensity": <integer>
}
}
ParameterTypeDescription
apiVersionStringThe API version that should be used.
contextStringThe client sets this value and the CGI will echo this context string back in the response (optional).
methodStringThe performed operation.
paramsJSON objectContainer for the method specific parameters.
lightIDStringThe light ID.
LEDIDIntegerThe ID of the LED.
intensityIntegerThe intensity level of the light.

Return value - Success

  • HTTP Code: 200 OK
  • Content-Type: application/json

Response body syntax

{
"apiVersion": "Major.Minor",
"context": "Echoed if provided by the client in the corresponding request",
"method": "setIndividualIntensity",
"data": {
}
}
ParameterTypeDescription
apiVersionStringThe API version that should be used.
contextStringThe client sets this value and the CGI will echo this context string back in the response (optional).
methodStringThe performed operation.
dataJSON objectContainer for the response specific parameters.

Return value - Failure

  • HTTP Code: 200 OK
  • Content-Type: application/json

Response body syntax

{
"apiVersion": "Major.Minor",
"context": "Echoed if provided by the client in the corresponding request",
"method": "The called method",
"error": {
"code": integer error code,
"message": "Error message"
}
}

Error codes

CodeDefinitionDescription
1001NOT_SUPPORTED_FAULTMethod call not supported by the device.
1002INVALID_LIGHT_ID_FAULTProvided lightID parameter is not valid for the device.
1003INVALID_INTENSITY_FAULTProvided intensity level is out of the supported range.
1005CARD_MALFUNCTIONING_FAULTCould not find light hardware, could not complete request.
1006WRONG_POE_CLASS_FAULTWrong POE class, could not complete request.

General errors are listed in General error codes.

getIndividualIntensity

A CGI method that sends the intensity in the setIndividualIntensity request.

Request

  • Security level: admin, operator
  • Method: POST
http://myserver/axis-cgi/lightcontrol.cgi

Request body syntax

{
"apiVersion": <major>.<minor>,
"context": <string>,
"method": "getIndividualIntensity",
"params": {
"lightID": <string>,
"LEDID": <integer>
}
}
ParameterTypeDescription
apiVersionStringThe API version that should be used.
contextStringThe client sets this value and the CGI will echo this context string back in the response (optional).
methodStringThe performed operation.
paramsJSON objectContainer for the method specific parameters.
lightIDStringThe light ID.
LEDIDIntegerThe ID of the LED.

Return value - Success

  • HTTP Code: 200 OK
  • Content-Type: application/json

Response body syntax

{
"apiVersion": "Major.Minor",
"context": "Echoed if provided by the client in the corresponding request",
"method": "getIndividualIntensity",
"data": {
"intensity": individualIntensity
}
}
ParameterTypeDescription
apiVersionStringThe API version that should be used.
contextStringThe client sets this value and the CGI will echo this context string back in the response (optional).
methodStringThe performed operation.
dataJSON objectContainer for the response specific parameters.
intensityIntegerThe currently configured individual intensity.

Return value - Failure

  • HTTP Code: 200 OK
  • Content-Type: application/json

Response body syntax

{
"apiVersion": "Major.Minor",
"context": "Echoed if provided by the client in the corresponding request",
"method": "The called method",
"error": {
"code": integer error code,
"message": "Error message"
}
}

Error codes

CodeDefinitionDescription
1001NOT_SUPPORTED_FAULTMethod call not supported by the device.
1002INVALID_LIGHT_ID_FAULTProvided lightID parameter is not valid for the device.
1005CARD_MALFUNCTIONING_FAULTCould not find light hardware, could not complete request.
1006WRONG_POE_CLASS_FAULTWrong POE class, could not complete request.

General errors are listed in General error codes.

getCurrentIntensity

A CGI method that gets the current intensity.

Request

  • Security level: admin, operator
  • Method: POST
http://myserver/axis-cgi/lightcontrol.cgi

Request body syntax

{
"apiVersion": <major>.<minor>,
"context": <string>,
"method": "getCurrentIntensity",
"params": {
"lightID": <string>
}
}
ParameterTypeDescription
apiVersionStringThe API version that should be used.
contextStringThe client sets this value and the CGI will echo this context string back in the response (optional).
methodStringThe performed operation.
paramsJSON objectContainer for the method specific parameters.
lightIDStringThe light ID.

Return value - Success

  • HTTP Code: 200 OK
  • Content-Type: application/json

Response body syntax

{
"apiVersion": "Major.Minor",
"context": "Echoed if provided by the client in the corresponding request",
"method": "getCurrentIntensity",
"data": {
"intensity": currentIntensity
}
}
ParameterTypeDescription
apiVersionStringThe API version that should be used.
contextStringThe client sets this value and the CGI will echo this context string back in the response (optional).
methodStringThe performed operation.
dataJSON objectContainer for the response specific parameters.
intensityIntegerThe current intensity of the light.

Return value - Failure

  • HTTP Code: 200 OK
  • Content-Type: application/json

Response body syntax

{
"apiVersion": "Major.Minor",
"context": "Echoed if provided by the client in the corresponding request",
"method": "The called method",
"error": {
"code": integer error code,
"message": "Error message"
}
}

Error codes

CodeDefinitionDescription
1001NOT_SUPPORTED_FAULTMethod call not supported by the device.
1002INVALID_LIGHT_ID_FAULTProvided lightID parameter is not valid for the device.
1005CARD_MALFUNCTIONING_FAULTCould not find light hardware, could not complete request.
1006WRONG_POE_CLASS_FAULTWrong POE class, could not complete request.

General errors are listed in General error codes.

setAutomaticAngleOfIlluminationMode

A CGI method that controls the automatic angle of illumination.

Request

  • Security level: admin, operator
  • Method: POST
http://myserver/axis-cgi/lightcontrol.cgi

Request body syntax

{
"apiVersion": <major>.<minor>,
"context": <string>,
"method": "setAutomaticAngleOfIlluminationMode",
"params": {
"lightID": <string>,
"enabled": <boolean>
}
}
ParameterTypeDescription
apiVersionStringThe API version that should be used.
contextStringThe client sets this value and the CGI will echo this context string back in the response (optional).
methodStringThe performed operation.
paramsJSON objectContainer for the method specific parameters.
lightIDStringThe light ID.
enabledBooleanActivate or deactivate automatic angle of illumination mode for a selected light.

Return value - Success

  • HTTP Code: 200 OK
  • Content-Type: application/json

Response body syntax

{
"apiVersion": "Major.Minor",
"context": "Echoed if provided by the client in the corresponding request",
"method": "setAutomaticAngleOfIlluminationMode",
"data": {
}
}
ParameterTypeDescription
apiVersionStringThe API version that should be used.
contextStringThe client sets this value and the CGI will echo this context string back in the response (optional).
methodStringThe performed operation.
dataJSON objectContainer for the response specific parameters.

Return value - Failure

  • HTTP Code: 200 OK
  • Content-Type: application/json

Response body syntax

{
"apiVersion": "Major.Minor",
"context": "Echoed if provided by the client in the corresponding request",
"method": "The called method",
"error": {
"code": integer error code,
"message": "Error message"
}
}

Error codes

CodeDefinitionDescription
1001NOT_SUPPORTED_FAULTMethod call not supported by the device.
1002INVALID_LIGHT_ID_FAULTProvided lightID parameter is not valid for the device.
1005CARD_MALFUNCTIONING_FAULTCould not find light hardware, could not complete request.
1006WRONG_POE_CLASS_FAULTWrong POE class, could not complete request.

General errors are listed in General error codes.

getValidAngleOfIllumination

A CGI method that lists the valid angle of the illumination values.

Request

  • Security level: admin, operator
  • Method: POST
http://myserver/axis-cgi/lightcontrol.cgi

Request body syntax

{
"apiVersion": <major>.<minor>,
"context": <string>,
"method": "getValidAngleOfIllumination",
"params": {
"lightID": <string>
}
}
ParameterTypeDescription
apiVersionStringThe API version that should be used.
contextStringThe client sets this value and the CGI will echo this context string back in the response (optional).
methodStringThe performed operation.
paramsJSON objectContainer for the method specific parameters.
lightIDStringThe light ID.

Return value - Success

  • HTTP Code: 200 OK
  • Content-Type: application/json

Response body syntax

{
"apiVersion": "Major.Minor",
"context": "Echoed if provided by the client in the corresponding request",
"method": "getValidAngleOfIllumination",
"data": {
"ranges": [
{
"low": lowerLimit,
"high": upperLimit
}
]
}
}
ParameterTypeDescription
apiVersionStringThe API version that should be used.
contextStringThe client sets this value and the CGI will echo this context string back in the response (optional).
methodStringThe performed operation.
dataJSON objectContainer for the response specific parameters.
rangesArrayArray of range objects.
lowIntegerLower angle limit for the range.
highIntegerUpper angle limit for the range.

Return value - Failure

  • HTTP Code: 200 OK
  • Content-Type: application/json

Response body syntax

{
"apiVersion": "Major.Minor",
"context": "Echoed if provided by the client in the corresponding request",
"method": "The called method",
"error": {
"code": integer error code,
"message": "Error message"
}
}

Error codes

CodeDefinitionDescription
1001NOT_SUPPORTED_FAULTMethod call not supported by the device.
1002INVALID_LIGHT_ID_FAULTProvided lightID parameter is not valid for the device.
1005CARD_MALFUNCTIONING_FAULTCould not find light hardware, could not complete request.
1006WRONG_POE_CLASS_FAULTWrong POE class, could not complete request.

General errors are listed in General error codes.

setManualAngleOfIllumination

A CGI method that sets the manual angle of illumination.

Request

  • Security level: admin, operator
  • Method: POST
http://myserver/axis-cgi/lightcontrol.cgi

Request body syntax

{
"apiVersion": <major>.<minor>,
"context": <string>,
"method": "setManualAngleOfIllumination",
"params": {
"lightID": <string>,
"angleOfIllumination": <integer>
}
}
ParameterTypeDescription
apiVersionStringThe API version that should be used.
contextStringThe client sets this value and the CGI will echo this context string back in the response (optional).
methodStringThe performed operation.
paramsJSON objectContainer for the method specific parameters.
lightIDStringThe light ID.
angleOfIlluminationIntegerThe angle of illumination.

Return value - Success

  • HTTP Code: 200 OK
  • Content-Type: application/json

Response body syntax

{
"apiVersion": "Major.Minor",
"context": "Echoed if provided by the client in the corresponding request",
"method": "setAutomaticAngleOfIlluminationMode",
"data": {
}
}
ParameterTypeDescription
apiVersionStringThe API version that should be used.
contextStringThe client sets this value and the CGI will echo this context string back in the response (optional).
methodStringThe performed operation.
dataJSON objectContainer for the response specific parameters.

Return value - Failure

  • HTTP Code: 200 OK
  • Content-Type: application/json

Response body syntax

{
"apiVersion": "Major.Minor",
"context": "Echoed if provided by the client in the corresponding request",
"method": "The called method",
"error": {
"code": integer error code,
"message": "Error message"
}
}

Error codes

CodeDefinitionDescription
1001NOT_SUPPORTED_FAULTMethod call not supported by the device.
1002INVALID_LIGHT_ID_FAULTProvided lightID parameter is not valid for the device.
1004INVALID_ANGLE_OF_ILLUMINATION_FAULTProvided angle of illumination is out of the supported range.
1005CARD_MALFUNCTIONING_FAULTCould not find light hardware, could not complete request.
1006WRONG_POE_CLASS_FAULTWrong POE class, could not complete request.

General errors are listed in General error codes.

getManualAngleOfIllumination

A CGI method that gets the angle of illumination sent by the setManualAngleOfIllumination request.

Request

  • Security level: admin, operator
  • Method: POST
http://myserver/axis-cgi/lightcontrol.cgi

Request body syntax

{
"apiVersion": <major>.<minor>,
"context": <string>,
"method": "getManualAngleOfIllumination",
"params": {
"lightID": <string>
}
}

getManualAngleOfIllumination request parameters

ParameterTypeDescription
apiVersionStringThe API version that should be used.
contextStringThe client sets this value and the CGI will echo this context string back in the response (optional).
methodStringThe performed operation.
paramsJSON objectContainer for the method specific parameters.
lightIDStringThe light ID.

Return value - Success

  • HTTP Code: 200 OK
  • Content-Type: application/json

Response body syntax

{
"apiVersion": "Major.Minor",
"context": "Echoed if provided by the client in the corresponding request",
"method": "getManualAngleOfIllumination",
"data": {
"angleOfIllumination": angle
}
}
ParameterTypeDescription
apiVersionStringThe API version that should be used.
contextStringThe client sets this value and the CGI will echo this context string back in the response (optional).
methodStringThe performed operation.
dataJSON objectContainer for the response specific parameters.
angleOfIlluminationIntegerThe current manual angle of illumination.

Return value - Failure

  • HTTP Code: 200 OK
  • Content-Type: application/json

Response body syntax

{
"apiVersion": "Major.Minor",
"context": "Echoed if provided by the client in the corresponding request",
"method": "The called method",
"error": {
"code": integer error code,
"message": "Error message"
}
}

Error codes

CodeDefinitionDescription
1001NOT_SUPPORTED_FAULTMethod call not supported by the device.
1002INVALID_LIGHT_ID_FAULTProvided lightID parameter is not valid for the device.
1005CARD_MALFUNCTIONING_FAULTCould not find light hardware, could not complete request.
1006WRONG_POE_CLASS_FAULTWrong POE class, could not complete request.

General errors are listed in General error codes.

getCurrentAngleOfIllumination

A CGI method that gets the current angle of illumination.

Request

  • Security level: admin, operator
  • Method: POST
http://myserver/axis-cgi/lightcontrol.cgi

Request body syntax

{
"apiVersion": <major>.<minor>,
"context": <string>,
"method": "getCurrentAngleOfIllumination",
"params": {
"lightID": <string>
}
}

getCurrentAngleOfIllumination request parameters

ParameterTypeDescription
apiVersionStringThe API version that should be used.
contextStringThe client sets this value and the CGI will echo this context string back in the response (optional).
methodStringThe performed operation.
paramsJSON objectContainer for the method specific parameters.
lightIDStringThe light ID.

Return value - Success

  • HTTP Code: 200 OK
  • Content-Type: application/json

Response body syntax

{
"apiVersion": "Major.Minor",
"context": "Echoed if provided by the client in the corresponding request",
"method": "getCurrentAngleOfIllumination",
"data": {
"angleOfIllumination": angle
}
}
ParameterTypeDescription
apiVersionStringThe API version that should be used.
contextStringThe client sets this value and the CGI will echo this context string back in the response (optional).
methodStringThe performed operation.
dataJSON objectContainer for the response specific parameters.
angleOfIlluminationIntegerThe currently active angle of illumination.

Return value - Failure

  • HTTP Code: 200 OK
  • Content-Type: application/json

Response body syntax

{
"apiVersion": "Major.Minor",
"context": "Echoed if provided by the client in the corresponding request",
"method": "The called method",
"error": {
"code": integer error code,
"message": "Error message"
}
}

Error codes

CodeDefinitionDescription
1001NOT_SUPPORTED_FAULTMethod call not supported by the device.
1002INVALID_LIGHT_ID_FAULTProvided lightID parameter is not valid for the device.
1005CARD_MALFUNCTIONING_FAULTCould not find light hardware, could not complete request.
1006WRONG_POE_CLASS_FAULTWrong POE class, could not complete request.

General errors are listed in General error codes.

setLightSynchronizeDayNightMode

A CGI method that let you enable or disable the automatic day/night synchronization mode.

Request

  • Security level: admin, operator
  • Method: POST
http://myserver/axis-cgi/lightcontrol.cgi

Request body syntax

{
"apiVersion": <major>.<minor>,
"context": <string>,
"method": "setLightSynchronizeDayNightMode",
"params": {
"lightID": <string>,
"enabled": <boolean>
}
}

setLightSynchronizeDayNightMode

ParameterTypeDescription
apiVersionStringThe API version that should be used.
contextStringThe client sets this value and the CGI will echo this context string back in the response (optional).
methodStringThe performed operation.
paramsJSON objectContainer for the method specific parameters.
lightIDStringThe light ID.
enabledBooleanActivate or deactivate automatic angle of illumination mode for a selected light.

Return value - Success

  • HTTP Code: 200 OK
  • Content-Type: application/json

Response body syntax

{
"apiVersion": "Major.Minor",
"context": "Echoed if provided by the client in the corresponding request",
"method": "setLightSynchronizeDayNightMode",
"data": {
}
}
ParameterTypeDescription
apiVersionStringThe API that should be used.
contextStringThe client sets this value and the CGI will echo this context string back in the response (optional).
methodStringThe performed operation.
dataJSON objectContainer for the response specific parameters.

Return value - Failure

  • HTTP Code: 200 OK
  • Content-Type: application/json

Response body syntax

{
"apiVersion": "Major.Minor",
"context": "Echoed if provided by the client in the corresponding request",
"method": "The called method",
"error": {
"code": integer error code,
"message": "Error message"
}
}

Error codes

CodeDefinitionDescription
1001NOT_SUPPORTED_FAULTMethod call not supported by the device.
1002INVALID_LIGHT_ID_FAULTProvided lightID parameter is not valid for the device.
1005CARD_MALFUNCTIONING_FAULTCould not find light hardware, could not complete request.
1006WRONG_POE_CLASS_FAULTWrong POE class, could not complete request.

General errors are listed in General error codes.

getLightSynchronizeDayNightMode

A CGI method that checks if the automatic synchronization with the day/night mode is enabled.

Request

  • Security level: admin, operator
  • Method: POST
http://myserver/axis-cgi/lightcontrol.cgi

Request body syntax

{
"apiVersion": <major>.<minor>,
"context": <string>,
"method": "getLightSynchronizeDayNightMode",
"params": {
"lightID": <string>
}
}

getLightSynchronizeDayNightMode

ParameterTypeDescription
apiVersionStringThe API version that should be used.
contextStringThe client sets this value and the CGI will echo this context string back in the response (optional).
methodStringThe performed operation.
paramsJSON objectContainer for the method specific parameters.
lightIDStringThe light ID.

Return value - Success

  • HTTP Code: 200 OK
  • Content-Type: application/json

Response body syntax

{
"apiVersion": "Major.Minor",
"context": "Echoed if provided by the client in the corresponding request",
"method": "getLightSynchronizeDayNightMode",
"data": {
"synchronize": true | false
}
}
ParameterTypeDescription
apiVersionStringThe API version that should be used.
contextStringThe client sets this value and the CGI will echo this context string back in the response (optional).
methodStringThe performed operation.
dataJSON objectContainer for the response specific parameters.
enabledBooleanIf the day/night cut filter synchronization of the light is active.

Return value - Failure

  • HTTP Code: 200 OK
  • Content-Type: application/json

Response body syntax

{
"apiVersion": "Major.Minor",
"context": "Echoed if provided by the client in the corresponding request",
"method": "The called method",
"error": {
"code": integer error code,
"message": "Error message"
}
}

Error codes

CodeDefinitionDescription
1001NOT_SUPPORTED_FAULTMethod call not supported by the device.
1002INVALID_LIGHT_ID_FAULTProvided lightID parameter is not valid for the device.
1005CARD_MALFUNCTIONING_FAULTCould not find light hardware, could not complete request.
1006WRONG_POE_CLASS_FAULTWrong POE class, could not complete request.

General errors are listed in General error codes.

getValidIRWavelengths

A CGI method that returns a list containing the infrared wavelengths.

  • HTTP Code: 200 OK
  • Content-Type: application/json

Request body syntax

{
"apiVersion": "Major.Minor",
"context": "Echoed if provided by the client in the corresponding request",
"method": "getValidIRWavelengths",
"params": {
"lightID": <string>,
}
}

getValidIRWavelength

ParameterTypeDescription
apiVersionStringThe API version that should be used.
contextStringThe client sets this value and the CGI will echo this context string back in the response (optional).
methodStringThe performed operation.
paramsJSON objectContainer for method specific parameters.
lightIDStringThe light ID.

Return value - Success

  • HTTP Code: 200 OK
  • Content-Type: application/json

Response body syntax

{
"apiVersion": "Major.Minor",
"context": "Echoed if provided by the client in the corresponding request",
"method": "getValidIRWavelengths",
"data": {
"settings": [
wavelength,
...
]
}
}
ParameterTypeDescription
apiVersionStringThe API that should be used.
contextStringThe client sets this value and the CGI will echo this context string back in the response (optional).
methodStringThe performed operation.
dataJSON objectContainer for the response specific parameters.
wavelengthsArrayAn array containing the wavelengths settings.

Return value - Failure

  • HTTP Code: 200 OK
  • Content-Type: application/json

Response body syntax

{
"apiVersion": "Major.Minor",
"context": "Echoed if provided by the client in the corresponding request",
"method": "The called method",
"error": {
"code": integer error code,
"message": "Error message"
}
}

Error codes

CodeDefinitionDescription
1001NOT_SUPPORTED_FAULTMethod call not supported by the device.
1002INVALID_LIGHT_ID_FAULTProvided lightID parameter is not valid for the device.
1005CARD_MALFUNCTIONING_FAULTCould not find light hardware, could not complete request.
1006WRONG_POE_CLASS_FAULTWrong POE class, could not complete request.

General errors are listed in General error codes.

setIRWavelength

A CGI method that sets the infrared wavelength.

Request

  • Security level: admin, operator
  • Method: POST
http://myserver/axis-cgi/lightcontrol.cgi

Request body syntax

{
"apiVersion": <major>.<minor>,
"context": <string>,
"method": "setIRWavelength",
"params": {
"lightID": <string>,
"IRWavelength": <string>
}
}
ParameterTypeDescription
apiVersionStringThe API version that should be used.
contextStringThe client sets this value and the CGI will echo this context string back in the response (optional).
methodStringThe performed operation.
paramsJSON objectContainer for the method specific parameters.
lightIDStringThe light ID.
IRWavelengthStringThe infrared wavelength.

Return value - Success

  • HTTP Code: 200 OK
  • Content-Type: application/json

Response body syntax

{
"apiVersion": "Major.Minor",
"context": "Echoed if provided by the client in the corresponding request",
"method": "setIRWavelength",
"data": {
}
}
ParameterTypeDescription
apiVersionThe API version that should be used.
contextThe client sets this value and the CGI will echo this context string back in the response (optional).
methodContainer for the response specific parameters.
dataThe current intensity of the light.

Return value - Failure

  • HTTP Code: 200 OK
  • Content-Type: application/json

Response body syntax

{
"apiVersion": "Major.Minor",
"context": "Echoed if provided by the client in the corresponding request",
"method": "The called method",
"error": {
"code": integer error code,
"message": "Error message"
}
}

Error codes

CodeDefinitionDescription
1001NOT_SUPPORTED_FAULTMethod call not supported by the device.
1002INVALID_LIGHT_ID_FAULTProvided lightID parameter is not valid for the device.
1005CARD_MALFUNCTIONING_FAULTCould not find light hardware, could not complete request.
1006WRONG_POE_CLASS_FAULTWrong POE class, could not complete request.
1007INVALID_IR_WAVELENGTH_FAULTProvided infrared wavelength is not valid.

General errors are listed in General error codes.

getIRWavelength

A CGI method that returns the current wavelength setting.

Request

  • Security level: admin, operator
  • Method: POST
http://myserver/axis-cgi/lightcontrol.cgi

Request body syntax

{
"apiVersion": "Major.Minor",
"context": "Echoed if provided by the client in the corresponding request",
"method": "getIRWavelength",
"params": {
"lightID": <string>
}
}

getIRWavelength

ParameterTypeDescription
apiVersionStringThe API version that should be used.
contextStringThe client sets this value and the CGI will echo this context string back in the response (optional).
methodStringThe performed operation.
paramsJSON objectContainer for method specific parameters.
lightIDStringThe light ID.

Return value - Success

  • HTTP Code: 200 OK
  • Content-Type: application/json

Response body syntax

{
"apiVersion": "Major.Minor",
"context": "Echoed if provided by the client in the corresponding request",
"method": "getIRWavelength",
"data": {
"IRWavelength": wavelength
}
}
ParameterTypeDescription
apiVersionStringThe API version that should be used.
contextStringThe client sets this value and the CGI will echo this context string back in the response (optional).
methodStringThe performed operation.
dataJSON objectContainer for the response specific parameters.
IRWavelengthStringAn array containing the wavelength settings.

Return value - Failure

  • HTTP Code: 200 OK
  • Content-Type: application/json

Response body syntax

{
"apiVersion": "Major.Minor",
"context": "Echoed if provided by the client in the corresponding request",
"method": "The called method",
"error": {
"code": integer error code,
"message": "Error message"
}
}

Error codes

CodeDefinitionDescription
1001NOT_SUPPORTED_FAULTMethod call not supported by the device.
1002INVALID_LIGHT_ID_FAULTProvided lightID parameter is not valid for the device.
1005CARD_MALFUNCTIONING_FAULTCould not find light hardware, could not complete request.
1006WRONG_POE_CLASS_FAULTWrong POE class, could not complete request.

General errors are listed in General error codes.

General error codes

The following table lists the general errors that can occur for any CGI method, while errors that are specific for a method are listed under their specific API descriptions.

CodeDefinitionDescription
1000PARAM_INVALID_VALUE_ERRORInvalid parameter value.
2000RESOURCE_MEM_ERRORFailed to allocate memory.
2001ACCESS_FORBIDDENAccess forbidden
2002HTTP_METHOD_NOT_SUPPORTEDHTTP request type not supported. Only POST supported.
2003API_VERSION_NOT_SUPPORTEDThe requested API version is not supported.
2004METHOD_NOT_SUPPORTEDMethod not supported.
3000UNSUPPORTED_API_VERSIONThe requested API version is not supported.
4000JSON_INVALID_ERRORThe provided JSON input was invalid.
4001JSON_KEY_NOT_FOUND_ERRORA mandatory input parameter was not found in the input.
4002JSON_INVALID_TYPEThe provided JSON parameter type was incorrect.
7000UNSUPPORTED_API_VERSIONThe requested API version is not supported by this implementation.
8000INTERNAL_ERRORInternal error.
8001UNEXPECTED_ERRORUnexpected error.
8002GENERIC_ERRORGeneric error.

Light control service API

info

For a newer version on how to use light control, see Light control API.

VAPIX® Light control service API enables applications and users to control built-in lights. Lights can be activated and inactivated using this API or using action rules. The API is a web services API.

A built-in light is an illuminator which is integrated in the Axis product. The illuminator improves the camera’s short-range visibility, in particular in low-light conditions, and can for example be an infrared LED (light emitting diode) or a white LED. In the API, a "light" is a single illuminator or a group of illuminators. Each light is identified by a unique Light ID.

Supported functionality:

  • Retrieve information about the light
  • Enable and activate light. Enabling allows clients and users to control the light. Activating turns the light on.
  • Synchronize with day/night mode. When synchronized, the light is automatically activated in night mode.
  • Control light intensity
  • Control angle of illumination. The angle of illumination (the width of the light beam) can be set to be adjusted automatically according to the camera’s angle of view.

Prerequisites

Identification

Use VAPIX® Entry service API to check if the API is supported.

  • Namespace: http://www.axis.com/vapix/ws/light
  • Firmware: 5.40
  • Product category: Products with built-in illuminators, for example infrared LEDs or white LEDs.

API specification

The API specification is available as an WSDL file at http://www.axis.com/vapix/ws/LightService.wsdl

Using the light control service

Identification

The example outlined in this section shows how to check if the light control service is supported and how to create a light service client.

To check if the Axis product supports the Light control service API, we use GetServices from VAPIX® Entry service API.

We start by defining the IP address, user name and password for the Axis product and the namespace of the light control service. Then, we use CreateEntryServiceClient to create an entry service client.

info

The function CreateEntryServiceClient is defined in the sample code and is not part of the API. For more information about the entry service, see the VAPIX® Entry service API documentation.

/* Define the address, user name and password for the Axis product. <ip-address> is an IP address or host name.*/
string address="<ip-address>";
string username="<user name>";
string password="<password>";

/* Define the namespace of the light control service.*/
string lightTargetNamespace = "http://www.axis.com/vapix/ws/light";

/* Create an Entry Service client.*/

EntryClient myEntryService = CreateEntryServiceClient(address, username, password);

Next, we use the entry service client and GetServices to get a list of all services in the Axis product. We search the list to check if the light control service is included.

If the service is found, we use CreateLightServiceClient() to create a light client. This function is not part of the API and is created in the same way as CreateEntryServiceClient.

/* Get a list of all services.*/
Service[] serviceList = myEntryService.GetServices(false);

/* Check if light control service is supported.*/
for (i = 0; i < serviceList.count; i++)
{
if (serviceList[i].Namespace == lightTargetNamespace)
{
/* Get the service address.*/
string lightXaddr = serviceList[i].Xaddr;

/* Create a light client.*/
LightClient myLightService = CreateLightServiceClient(lightXaddr, username, password);

break;
}
}

Light information

The following functions can be used to retrieve information about the light:

  • The following functions can be used to retrieve information about the light:

    GetServiceCapabilities — list the supported light control service capabilities.

  • GetLightInformation — list light information such as the Light ID, type of light, if the light is enabled and error information

  • GetLightStatus — check if the light is active or inactive

This example shows how to list the capabilities provided by the light control service.

To list the service capabilities, we use the light service client myLightService created in section Identification and GetServiceCapabilities.

/* Get the service capabilities.*/
Capabilities LightCapabilities = myLightService.GetServiceCapabilities();

This example shows how to list information about the light and how to retrieve the Light ID. We use the light service client myLightService and the GetLightInformation request.

GetLightInformation returns a list of light information for all lights. From the list, we can retrieve information about a particular light. Here, we will retrieve the Light ID of the first light.

/* Get a list of light information for all lights.*/
LightInformationList[] lightInformationList = myLightService.GetLightInformation();

/* Get the Light ID for the first light.*/
LightInformation lightInformation = lightInformationList[0];
string lightID = lightInformation.LightID;

In this example, we use the light service client myLightService, the lightID and the GetLightStatus request to check if the light is lit.

/* Check if the light is lit.*/
if (myLightService.GetLightStatus(lightID))
{
Console.WriteLine("The light is lit");
}
else
{
Console.WriteLine("The light is not lit");
}

Enable and activate the light

To allow users and clients to control the light, the light must first be enabled. Activating turns the light on.

For products with an IR cut filter, an IR light cannot be activated if the IR cut filter is in "On" mode (that is, when the IR cut filter is blocking IR light).

Supported operations:

  • Supported operations:

    ActivateLight — turn on the light

  • DeactivateLight — turn off the light

  • EnableLight — enable the light control functionality

  • DisableLight — disable the light control functionality. This prevents users and clients from turning on the light.

This example shows to how check if the light is enabled, enable the light and turn it on.

In the example, we use the light service client myLightService created in section Identification and lightInformationList with information about all lights from section Light information.

/* Get the Light ID.*/
LightInformation lightInformation = lightInformationList[0];
string lightID = lightInformation.LightID;

/* Check if the light is enabled.*/
if (!lightInformation.Enabled)
{
/* Enable the light.*/
myLightService.EnableLight(lightID);
/* Turn on the light.*/
myLightService.ActivateLight(lightID);
}

/* Inform user that light is lit.*/
if (myLightService.GetLightStatus(lightID))
{
Console.WriteLine("The light is lit");
}

Light intensity

The light intensity can be controlled automatically or set manually. Due to power and heat constraints, the actual light intensity might be lower than the set value.

info

Support for automatic mode is product dependent. Functionality may differ depending on product model.

Supported operations:

  • Supported operations:

    SetAutomaticIntensityMode — enable automatic light intensity control

  • SetManualIntensity — set the intensity manually

  • GetManualIntensity — get the intensity sent in the SetManualIntensity request

  • GetCurrentIntensity — get the current light intensity

  • GetValidIntensity — list valid light intensity values

This example shows how to list valid light intensity values.

In the example, we use the light service client myLightService created in section Identification and lightInformationList with information about all lights from section Light information.

/* Get the Light ID.*/
LightInformation lightInformation = lightInformationList[0];
string lightID = lightInformation.LightID;

/* Get valid light intensities.*/
IntRangeList[] validIntensityList = myLightService.GetValidIntensity(lightID);

/* Print the valid intensity range.*/
for (i = 0; i < validIntensityList.Count; i++)
{
IntRange validRange = validIntensityList[i];
Console.WriteLine("Valid Intensities are {0} - {1}", validRange.Low, validRange.High);
}

Angle of illumination

The angle of illumination defines the width of the light beam. A small angle of illumination gives a narrow beam, a large angle of illumination gives a wide beam.

The angle of illumination can be controlled automatically or set manually. Automatic mode can be used if the product supports absolute zoom (parameter PTZ.Support.S#.AbsoluteZoom=true). In automatic mode, the angle of illumination is set according to the camera’s angle of view and will be adjusted when the angle of view changes.

Supported operations:

  • Supported operations:

    SetAutomaticAngleOfIlluminationMode — control the angle of illumination automatically

  • SetManualAngleOfIllumination — set the angle of illumination manually

  • GetManualAngleOfIllumination — get the angle of illumination sent in the SetManualAngleOfIllumination request

  • GetCurrentAngleOfIllumination — get the current angle of illumination

  • GetValidAngleOfIllumination — list valid angle of illumination values

This example shows how to get the current angle of illumination.

In the example, we use the light service client myLightService created in section Identification and lightInformationList with information about all lights from section Light information.

/* Get the Light ID.*/
LightInformation lightInformation = lightInformationList[0];
string lightID = lightInformation.LightID;

/* Get and print the current angle of illumination.*/
int angleOfIllumination = myLightService.GetCurrentAngleOfIllumination(lightID);
Console.WriteLine("Current angle of illumination: {0} ", angleOfIllumination);

This example shows how to turn off the automatic mode and set the angle to 50.

/* Turn off automatic angle of illumination.*/
myLightService.SetAutomaticAngleOfIlluminationMode(lightID, false);

/* Set the angle of illumination to 50.*/
myLightService.SetManualAngleOfIllumination(lightID, 50);

/* Get and print the current angle of illumination.*/
int angleOfIllumination = myLightService.GetCurrentAngleOfIllumination(lightID);
Console.WriteLine("Current angle of illumination: {0} ", angleOfIllumination);

Synchronize with day/night mode

For products with day/night mode capabilities, the light can be synchronized with day/night mode so that the light is automatically activated in night mode. For products with an IR cut filter, an IR light can be synchronized with day/night mode if the IR cut filter is in "Auto" or "Off" mode.

Supported operations:

  • Supported operations:

    GetLightSynchronizeDayNightMode — check if synchronization with day/night mode is enabled.

  • SetLightSynchronizeDayNightMode — enable or disable automatic synchronization with day/night mode