update_sensor

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

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>
        }
    ]
}

The request must contain the following parameters:

To create or update a sensor, the following parameters are also required:

For further information about sensor types, see Sensor types.

The following parameters are used to configure a sensor:

"{
  \"act\": <bool>,
  \"appear_in_popup\": <bool>,
  \"battery_capacity\": <double>,
  \"ci\": <object>,
  \"calc_fuel\": <uint>,
  \"engine_efficiency\": <array>,
  \"engine_sensors\": <array>,
  \"filter\": <long>,
  \"fuel_params\": <object>,
  \"mu\": <uint>,
  \"pos\": <uint>,
  \"show_time\": <bool>,
  \"unbound_code\": <text>,
  \"validate_driver_unbound\": <bool>,
  \"do_not_show\": <bool>,
  \"timeout\": <uint>,
  \"uct\": <bool>,
  \"lower_bound\": <double>,
  \"upper_bound\": <double>,
  \"overflow_limit\": <double>,
  \"text_params\": <uint>,
  \"show_as_percentage\": <uint>
}"

The c parameter is sent as a string containing a JSON object. Enclose the object in double quotes and escape the double quotes in its keys and values ("). See the configuration examples below.

Set sensor flags in the top-level f parameter. Don’t set c.flags directly.

In the ci parameter, each key is the lower bound of an interval, and each value describes how the sensor value is displayed in this interval:

"c":"{\"ci\":{\"0\":{\"t\":\"Off\",\"c\":16711680},\"50\":{\"t\":\"On\"}}}"

To set an interval without a lower bound, use the "-Infinity" key.

Example of passing fuel_params of a fuel level sensor:

"c":"{\"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:

"c":"{\"fuel_params\":{\"maxImpulses\":10,\"skipZero\":0}}"

Example of passing fuel_params of a battery level sensor:

"c":"{\"fuel_params\":{\"flags\":16387,\"filterQuality\":0,\"minFillingVolume\":10,\"fillingsJoinInterval\":300}}"

For a battery level sensor, the system uses the settings listed below. If you don’t pass the fuel_params object at all, the system uses the fuel settings of the unit. If you pass the object without some of the keys, the system uses the values from the table.

The system uses these settings only when data calculation by the sensor is enabled in calc_fuel. This setting corresponds to the Calculate data by the sensor option. The calculated values are returned by the battery_level, charge, and ev detectors. For details, see the Event detector types section.

The show_as_percentage key affects display only. Always specify battery_capacity and charge detection settings in kWh.

Example of a c string for a battery level sensor that sets both charge detection and percentage display:

"c":"{\"fuel_params\":{\"flags\":16387,\"filterQuality\":0,\"minFillingVolume\":10,\"fillingsJoinInterval\":300},\"show_as_percentage\":1,\"battery_capacity\":64.5,\"calc_fuel\":2,\"act\":1,\"mu\":0,\"appear_in_popup\":true}"

Pass show_as_percentage and battery_capacity inside the c string, next to fuel_params, and keep the m parameter of the sensor set to kWh.

The filtering type is set in flags: use 0x02 to enable filtering and add 0x4000 for adaptive median filtering. If you set the 0x2000 flag, the system uses only the filtering flags and the filterQuality value of the sensor.

For battery level sensors, the 0x2000 flag works in the opposite way to its description on the unit/get_fuel_settings page: it doesn’t apply the default fuel settings of the unit.

The system always adds the calculation-by-time mode (0x10) for battery level sensors. You can’t disable it through this method.

For battery level sensors, the system resets the ignoreStayTimeout, minTheftVolume, and extraFillingTimeout keys to 0, even if you specify other values. The minTheftTimeout and theftsJoinInterval keys have no effect because drain detection isn’t available for these sensors.

If the request to create or update 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>",      /* Unit of measurement */
    "p": "<text>",      /* Parameter */
    "f": <uint>,        /* Sensor flags */
    "c": <text>,        /* Configuration, sent and returned as a JSON string */
    "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:

[
  <long>,   /* Sensor ID */
  null
]

If the request fails, an error code is returned.