Temperature control
Description
The Temperature control API provides the information that makes it possible for applications and users to monitor and control the temperature of an Axis product. This includes monitoring the temperature sensors and controlling the heaters as well as the fans. Since the availability of these components are product specific this API also includes how to retrieve this information.
Model
The API implements the following CGI:s as its communications interface that allows you to do the following:
| Function | Description |
|---|---|
temperaturecontrol.cgi | Retrieves all information about available temperature sensors, heaters and fans. This CGI can also be used to directly control the heaters and fans. |
param.cgi | Specifies the trigger levels for user configured events. |
Identification
- API Discovery:
id=temperaturecontrol - Property:
Properties.TemperatureSensor.TemperatureControl=yes - Property:
Properties.TemperatureSensor.Fan=yes | no - Property:
Properties.TemperatureSensor.Heater=yes | no
Common examples
Remove fog on camera window
Use these examples to get rid of fog on the front window of the camera that may have built up due to changing weather conditions. Depending on your product, this can either be done by running a heater or a fan.
Initiate the heater manually
- Turn on the heater, which in this example has the id 0.
http://<servername>/axis-cgi/temperaturecontrol.cgi?device=heater&id=0&action=start
- Parse the HTTP response.
Successful response example
OK
Stop the fan
- Stop the fan, which in this example has the id 1, from running.
http://<servername>/axis-cgi/temperaturecontrol.cgi?device=fan&id=1&action=stop
- Parse the HTTP response.
Successful response example
OK
Set duration for a manual heater control
- Set the manual activation time for a heater, which in this example has the id 0.
http://<servername>/axis-cgi/param.cgi?action=update&TemperatureControl.Heater.H0.ManualControlDuration=120
- Parse the HTTP response.
Successful response example
OK
Activate user control mode
- Enable the user control for a heater, which in this example has the id 1, and set the heater intensity to 50%.
http://<servername>/axis-cgi/temperaturecontrol.cgi?device=heater&id=1&usercontrolmode=true&intensity=50
- Parse the HTTP response.
Successful response example
OK
Fail to start heater
- Request a non-existing heater with id 1 to turn on.
http://<servername>/axis-cgi/temperaturecontrol.cgi?device=heater&id=1&action=start
- Parse the HTTP response.
Error response example
Unknown device type or bad id.
Unsupported action for fan
- Request a non-existing action for a fan, which in this example has the id 1.
http://<servername>/axis-cgi/temperaturecontrol.cgi?device=fan&id=1&action=badaction
- Parse the HTTP response.
Error response example
Unsupported action.
User control mode not supported
- Request to enable user control of a heater, which in this example has the id 0, when this is not supported.
http://<servername>/axis-cgi/temperaturecontrol.cgi?device=heater&id=0&usercontrolmode=true
- Parse the HTTP response.
Error response example
Could not set the requested mode for the device.
Retrieve temperature information
Use these examples when you want to retrieve information about the temperature sensors, heaters and fans. This is useful when you want to understand the camera status.
Get all temperature information
- Retrieve all status information for the temperature sensors, heaters and fans.
http://<servername>/axis-cgi/temperaturecontrol.cgi?action=statusall
- Parse the HTTP response.
Successful response example
Sensor.S0.Name=Main
Sensor.S0.Celsius=43.50
Sensor.S0.Fahrenheit=110.30
Sensor.S1.Name=CPU
Sensor.S1.Celsius=50.44
Sensor.S1.Fahrenheit=122.79
Sensor.S2.Name=Image Sensor
Sensor.S2.Celsius=46.67
Sensor.S2.Fahrenheit=116.00
Sensor.S3.Name=Optics
Sensor.S3.Celsius=38.66
Sensor.S3.Fahrenheit=101.58
Heater.H0.Status=Stopped
Heater.H0.TimeUntilStop=0
Heater.H1.Status=Stopped
Heater.H1.TimeUntilStop=0
Fan.F0.Status=Stopped
Fan.F0.TimeUntilStop=0
Possible entries for the statusall response
| Parameter name | Description |
|---|---|
Sensor.S# | A temperature sensor with the index #. |
Sensor.S#.Name | The name of the temperature sensor #. |
Sensor.S#.Celsius | The degrees (in Celsius) reading from the temperature sensor #. |
Sensor.S#.Fahrenheit | The degrees (in Fahrenheit) reading from the temperature sensor #. |
Heater.H# | A heater with the index #. |
Heater.H#.Status | The status of heater #. See the table Possible status of heater below for possible values. |
Heater.H#.TimeUntilStop | The number of seconds left until heater # stops following manual activation. |
Fan.F# | A fan with the index #. |
Fan.F#.Status | The status of fan #. See the table Possible status of fan below for possible values. |
Fan.F#.TimeUntilStop | The number of seconds left until fan # stops following manual activation. |
Possible status of heater
| Value | Description |
|---|---|
Heater Failure | Heater has failed for some reason. |
Running | Heater is active. |
Running[XX] | Heater is active at certain XX intensity. Can be both a percentage or some other product specific representation. |
Stopped | The heater is stopped. |
Possible status of fan
| Value | Description |
|---|---|
Fan Failure | Fan has failed for some reason. |
Running | Fan is active. |
Running[XX] | Fan is active at certain XX intensity. Can be both a percentage or some other product specific representation. |
Stopped | The fan is stopped. |
Time until heater stops
- Retrieve time left until heater number 1 stops following a manual start.
http://<servername>/axis-cgi/temperaturecontrol.cgi?device=heater&id=1&action=timeuntilstop
- Parse the HTTP response.
Successful response example
95
Read temperature sensor in Celsius
- Retrieve the current temperature value in Celsius as measured by temperature sensor number 2.
http://<servername>/axis-cgi/temperaturecontrol.cgi?device=sensor&id=2&action=query
- Parse the HTTP response.
Successful response example
46.71
Read temperature sensor in Fahrenheit
- Retrieve the current temperature value in Fahrenheit as measured by temperature sensor number 2.
http://<servername>/axis-cgi/temperaturecontrol.cgi?device=sensor&id=2&action=query&temperatureunit=fahrenheit
- Parse the HTTP response.
Successful response example
116.07
Read current heater status
Retrieve the current status of a heater with id 1.
http://<servername>/axis-cgi/temperaturecontrol.cgi?device=heater&id=1&action=query
- Parse the HTTP response.
Successful response example
Running[100%]
Read temperature sensor on an invalid unit
- Retrieve the current temperature value from a malformed unit measured by temperature sensor number 2.
http://<servername>/axis-cgi/temperaturecontrol.cgi?device=sensor&id=2&action=query&temperatureunit=badunit
- Parse the HTTP response.
Error response example
Invalid temperature unit.
Configure temperature triggers
Use these examples to change the configured temperature limit for when an event is sent out, which is useful when you want to catch an event and react to it.
Set low trigger for sensor 2 in Celsius
- Set the low temperature trigger for temperature sensor 2 to -10 degrees Celsius.
http://<servername>/axis-cgi/param.cgi?action=update&TemperatureControl.Sensor.S2.TriggerLow=-10
- Parse the HTTP response.
Successful response example
OK
Set high trigger for sensor 3 in Fahrenheit
- Set the high temperature trigger for temperature sensor 3 to 30 degrees Fahrenheit.
http://<servername>/axis-cgi/param.cgi?action=update&TemperatureControl.Sensor.S3.TriggerHigh=30F
- Parse the HTTP response.
Successful response example
OK
Set low trigger for a sensor with bad id
- Set the low temperature trigger for a temperature sensor with bad or nonexistent id.
http://<servername>/axis-cgi/param.cgi?action=update&TemperatureControl.Sensor.S20.TriggerLow=-10
- Parse the HTTP response.
Error response example
# Error: Error setting 'root.TemperatureControl.Sensor.S20.TriggerLow' to '-10'!
API specifications
temperaturecontrol.cgi
Use this API to manage and retrieve information about temperature sensors, heaters and fans. Please note that the availability of all functionality except action=statusall depends on what kind of hardware your product has as well as the capabilities of the hardware.
Request
- Security level: Operator
- Method:
GET
http://<servername>/axis-cgi/temperaturecontrol.cgi?<argument>=<data>[&<argument>=<data>[&...]]
| Parameter | Description |
|---|---|
action=start | stop | query | timeuntilstop | statusall | Optional parameter that defines what should happen. Valid values are: - start: Manually starts the heater/fan for the duration set in ManualControlDuration parameter.- stop: Manually stops the heater/fan. Any duration left in timeuntilstop will be reset.- query: Retrieve information about heater/fan.- timeuntiltimestop: Retrieve information left on heater/fan.- statusall: Retrieve information on all heater/fans/sensors. |
device=heater | fan | sensor | Optional parameter that defines the type of temperature device - heater: The device is a heater.- fan: The device is a fan.- sensor: The device is a temperature sensor. |
id=<id> | Optional parameter that defines the index number of the temperature device as an integer value. |
usercontrolmode=true | false([^1]) | Optional parameter that is used to enable/disable manual control of a heater/fan. The control is reset to false whenever the device is rebooted- true: Enable user control mode.- false: Disable user control mode. |
temperatureunit=celsius | fahrenheit | Optional parameter that defines the temperature unit - celsius: Use Celsius- fahrenheit: Use Fahrenheit |
intensity=<0-100> | Optional parameter that defines the intensity of the heater/fan as an integer in the range between 0–100 percent. |
[1]: Dependant on device and their heater/fan capabilities. See product documentation for more information.
Return value - Success
-
HTTP Code:
200 OK -
Content-Type
text/html
Response body syntax
OK
Return value - Error
| HTTP code | Description |
|---|---|
400 | Malformed request. Return body specifies one of the following reasons. |
400 | The request had bad syntax or was inherently impossible to satisfy. |
400 | Unsupported action. |
400 | Unknown device type or bad id. |
400 | Invalid temperature unit. |
400 | Could not set the requested mode for the device. |
500 | Internal server error. |
TemperatureControl.Heater
Use the parameters in this group to configure the temperature control heater.
- List security level: Viewer
- Update security level: Operator or N/A
TemperatureControl.Heater.H#.<parameter>
Valid values of # ranges from 0 to the number of heaters specified for the product -1. Please note that if UserControlSupport=no then all parameters have Update Security level N/A.
| Parameter | Description |
|---|---|
UserControlSupport=yes | no | Update security level: N/A. A read-only parameter specifying whether the user is allowed to control the heater or not. This parameter is static and will not be changed during the runtime. Default value is product and heater/fan specific. |
ManualControlDuration=<integer> | Specifies the time duration in seconds of a start action for the heater performed via temperaturecontrol.cgi. Valid ranges as well as the default value is product and heater/fan specific. |
ControlPolicyLimit=<integer> | Specifies the temperature limit around which temperature based, automatic control of the heater shall start. Together with ControlPolicyDelta a temperature range for the heater is created. |
ControlPolicyDelta=<integer> | Specifies the size of the range used for creating the temperature based, automatic control of the heater. |
TemperatureControl.Fan
Use the parameters in this group to configure the temperature control fan.
- List security level: Viewer
- Update security level: Operator or N/A
TemperatureControl.Fan.F#.<parameter>
Valid values of # ranges from 0 to the number of heaters specified for the product -1. Please note that if UserControlSupport=no then all parameters have Update Security level N/A.
| Parameter | Description |
|---|---|
UserControlSupport=yes | no | Update security level: N/A. A read-only parameter specifying whether the user is allowed to control the fan or not. This parameter is static and will not be changed during the runtime. Default value is product and heater/fan specific. |
ManualControlDuration=<integer> | Specifies the time duration in seconds of a start action for the fan performed via temperaturecontrol.cgi. Valid ranges as well as the default value is product and heater/fan specific. |
ControlPolicyLimit=<integer> | Specifies the temperature limit around which temperature based, automatic control of the heater shall start. Together with ControlPolicyDelta a temperature range for the fan is created. |
ControlPolicyDelta=<integer> | Specifies the size of the range used for creating the temperature based, automatic control of the fan. |
TemperatureControl.Sensor
Use the parameters in this group to configure the temperature control sensor.
- List security level: Viewer
- Update security level: Operator or N/A
TemperatureControl.Sensor.S#.<parameter>
Valid values of # ranges from 0 to the number of heaters specified for the product -1.
| Parameter | Description |
|---|---|
Name=<string> | Specifies the name of the temperature sensor. |
TriggerHigh=<integer> | Specifies the temperature limit for which the Temperature above event is triggered. |
TriggerLow=<integer> | Specifies the temperature limit for which the Temperature below event is triggered. |