update_sensor

To create, edit or delete sensors, use the unit/update_sensor method:

Copied!
svc=unit/update_sensor&params={
    "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:

  • mileage
  • absolute fuel consumption
  • engine hours

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:

Copied!
"{
  \"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>
}"

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 0 — On, 1 — Off.
This option uses inverted logic:
  • Enabled state (value 0) refers to the older, historic logic version.
  • Disabled state (value 1) refers to the newer logic version (data is used for popups, which is useful when important parameters are received infrequently).
By default, the older logic version is selected.
appear_in_popup True — enable, false — disable.
ci Custom intervals.
filter Allows redefining the filtering level. Valid for the following sensors:
  • Fuel level
  • Temperature
  • Engine revolutions
  • Voltage
  • Accelerometer
  • Custom
  • Weight
mu Measurement system:
  • 0 — SI
  • 1 — US
  • 2 — imperial
  • 3 — metric with gallons
    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 0 - off, 1 - on.
    lower_bound Lower bound of valid sensor values for the calculation table.
    upper_bound Upper bound of valid sensor values for the calculation table.
    calc_fuel Specify 1 to activate fuel consumption calculation in reports.
    fuel_params Fuel level sensor settings.
    engine_sensors ID of engine sensors for a fuel level sensor to calculate proper consumption.
    engine_efficiency ID of engine efficiency sensors for engine sensors.

    Example of a sensor configuration:

    Copied!
    "c":"{\"appear_in_popup\":true,\"pos\":1,\"ci\":{}}"
    

    Example of passing fuel_params of a fuel level sensor:

    Copied!
    "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:

    Copied!
    "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:

    Copied!
    [
      <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:

    Copied!
    [
      <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.

    If you find a mistake in the text, please select it and press Ctrl+Enter.

    Report a mistake

    Your message was sent. Thank you!

    An error occurred while submitting the form

    Download PDF file
    Download Word document

    See also