update_sensor
To create, edit or delete sensors, use the unit/update_sensor method:
svc=unit/update_sensor¶ms={
"itemId": <long>,
"id": <long>,
"callMode": <text>,
"unlink": <uint>,
"n": <text>,
"t": <text>,
"d": <text>,
"m": <text>,
"p": <text>,
"f": <uint>,
"c": <text>,
"vt": <uint>,
"vs": <long>,
"tbl": [
{
"x": <double>,
"a": <double>,
"b": <double>
}
]
}
Parameters
The request must contain the following parameters:
| Parameter | Description |
|---|---|
| itemId | Unit ID. |
| id | Sensor ID. Pass 0 if you want to create a sensor. |
| callMode | Action: create, update, delete. |
| unlink | Delete links with other sensors and unit parameters: 1 — yes (default), 0 — no. |
To create or update a sensor, the followig parameters are also required:
| Parameter | Description |
|---|---|
| n | Name |
| t | Type (see below). |
| d | Description. |
| m | Metrics. |
| p | Parameter. |
| f | Sensor flags (see below). |
| c | Configuration (see below). |
| vt | Validation type (see below). |
| vs | Validating sensor ID. |
| tbl | Calculation table. |
Sensor flags
| Flag | Description |
|---|---|
| 0x01 | Sensor type: instant. |
| 0x02 | Sensor type: differential. |
| 0x03 | Sensor type: differential with overflow (2 bytes). |
| 0x04 | Sensor type: switch from off to on. |
| 0x05 | Sensor type: switch from on to off. |
| 0x20 | Activate the With overflow option. Can be used for the following sensors:
If flag 0x20 is not set, the sensor works as follows: the change delta is calculated as abs(V2 - V1), where V2 is the value from the new message, V1 is the value from the previous message, and abs() denotes the absolute value. If the flag is set and V2 < V1, then the delta is equal to V2 (i.e., V1 is assumed to be 0). |
| 0x40 | Apply the lower and upper bounds after calculation. If the flag is not set, then each bound is applied to raw data (in the case of FLS, there are difficulties with setting lower and upper bounds for raw data). If the flag is set, then each bound is applied to calculated (processed) data. |
Sensor types
| Value | Sensor Type |
|---|---|
| Absolute fuel consumption | Absolute fuel consumption sensor |
| Accelerometer | Accelerometer |
| Alarm trigger | Alarm trigger |
| Counter | Counter sensor |
| Custom | Custom sensor |
| Digital | Custom digital sensor |
| Driver | Driver assignment |
| Engine efficiency | Engine efficiency sensor |
| Engine hours | Absolute engine hours |
| Engine operation | Engine ignition sensor |
| Engine RPM | Engine revolutions sensor |
| Fuel level impulse sensor | Impulse fuel level sensor |
| Fuel level | Fuel level sensor |
| Impulse fuel consumption | Impulse fuel consumption sensor |
| Instant fuel consumption | Instant fuel consumption sensor |
| Mileage | Mileage sensor |
| Odometer | Relative odometer |
| Private mode | Private mode |
| Relative engine hours | Relative engine hours |
| Temperature coefficient | Temperature coefficient |
| Temperature | Temperature sensor |
| Trailer | Trailer assignment |
| Voltage | Voltage sensor |
| Weight sensor | Weight sensor |
For further information about sensor types, see Sensor types.
Sensor configuration parameters
The following parameters are used to configure a sensor:
"{
\"act\": <bool>,
\"appear_in_popup\": <bool>,
\"ci\": <object>,
\"filter\": <long>,
\"mu\": <uint>,
\"pos\": <uint>,
\"show_time\": <text>,
\"unbound_code\": <text>,
\"validate_driver_unbound\": <bool>,
\"timeout\": <uint>,
\"uct\": <bool>,
\"lower_bound\": <double>,
\"upper_bound\": <double>,
\"text_params\": <uint>
}"
The JSON object must be enclosed in double quotes because it is sent as a string. All key and value double quotes must be escaped (").
| Parameter | Description |
|---|---|
| act | Sensor value calculation: 0 — based on the last unit parameters, 1 — based on the last unit message. This option uses inverted logic:
|
| appear_in_popup | True — enable the Visible option, false — disable. |
| ci | Custom intervals. |
| filter | Allows redefining the filtering level. Valid for the following sensors:
|
| mu | Measurement system:
|
| pos | Sensor position in the list (count from 1) |
| show_time | True — display the sensor value with the time since which this value was received. False — don’t show time. For further information, read about the Time option on the Sensors page. |
| unbound_code | For the driver or trailer assignment sensors, you can specify a custom separation code. |
| validate_driver_unbound | Validate separation: 0 — no, 1 — yes. |
| timeout | Timeout, seconds. |
| uct | Pass 0 to enable the Overflow by raw data option. Pass 1 to disable it. The option is available only for available only for the differential counter sensors with overflow. |
| lower_bound | Lower bound of valid sensor values for the calculation table. |
| upper_bound | Upper bound of valid sensor values for the calculation table. |
| txt_params | Pass 1 to enable the Text parameters option, or 0 to disable it. |
| calc_fuel | Specify 1 to activate fuel consumption calculation in reports. |
| fuel_params | Fuel level sensor settings. |
| engine_sensors | IDs of engine sensors for a fuel level sensor to calculate proper consumption. |
| engine_efficiency | IDs of engine efficiency sensors for engine sensors. |
Example of a sensor configuration:
"c":"{\"appear_in_popup\":true,\"pos\":1,\"ci\":{}}"
Example of passing fuel_params of a fuel level sensor:
"fuel_params":{\"flags\":1728,\"ignoreStayTimeout\":20,\"minFillingVolume\":21,\"minTheftTimeout\":0,\"minTheftVolume\":15,\"filterQuality\":0,\"fillingsJoinInterval\":300,\"theftsJoinInterval\":300,\"extraFillingTimeout\":0}
Example of passing fuel_params of an impulse fuel consumption sensor:
"fuel_params":{\"maxImpulses\":10, \"skipZero\":0}
Validation types
| Validation type flag | Description |
|---|---|
| 0x01 | Logical AND |
| 0x02 | Logical OR |
| 0x03 | Math AND |
| 0x04 | Math OR |
| 0x05 | Sum up |
| 0x06 | Subtract validator from sensor |
| 0x07 | Subtract sensor from validator |
| 0x08 | Multiply |
| 0x09 | Divide sensor by validator |
| 0x0A | Divide validator by sensor |
| 0x0B | Not-null check |
| 0x0C | Replace sensor with validator in case of error |
Response
If the request to create or edit a sensor is completed successfully, a response in the following format is returned:
[
<long>, /* sensor ID */
{
"id": <long>, /* Sensor ID */
"n": "<text>", /* Name */
"t": "<text>", /* Type */
"d": "<text>", /* Description */
"m": "<text>", /* Metrics */
"p": "<text>", /* Parameter */
"f": <uint>, /* Sensor flags */
"c": <object>, /* Configuration */
"vt": <int>, /* validation type */
"vs": <long>, /* Validating sensor ID */
"tbl": [ /* Calculation table */
{
"x": <double>,
"a": <double>,
"b": <double>
}
]
}
]
If the request to delete a sensor is completed successfully, a response in the following format is returned:
[
<sensor_id>, // sensor ID
null
]
If the request fails, an error code is returned.
Error codes
| Error code | Description |
|---|---|
| 4 | Wrong input parameters. |
| 6 | Failed to update a parameter from the params section. |
| 7 | No ADF_ACL_AVL_UNIT_EDIT_SENSORS access right to the unit. |
| 2015 | Unable to delete the sensor because it is used in the advanced properties of the unit or in the properties of another sensor. |