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 delete a sensor, you can also pass the following parameter:

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. The system stores the value of f in the flags key of the c string. That’s why, if f isn’t 0, the returned c string contains this key as a string value, for example, \"flags\":\"1\". If the c string that you pass already contains the flags key, the value of f is ignored.

If the c value isn’t valid JSON, the system ignores it and doesn’t return an error. The sensor is saved with an empty configuration, which contains only the flags key if f isn’t 0.

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 binding the engine sensors with IDs 3 and 5 to a fuel level sensor:

"c":"{\"engine_sensors\":[3,5]}"

Example of binding the engine efficiency sensor with ID 7 to an engine ignition sensor. This binding is taken into account only for the fuel level sensors that have this engine ignition sensor in engine_sensors:

"c":"{\"engine_efficiency\":[7]}"

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

For fuel level and impulse fuel consumption sensors, the fuel_params object overrides the unit fuel settings (fuelLevelParams and fuelConsImpulse). If you don’t pass the object, the system uses the settings of the unit. If you pass the object without some of the keys, the system doesn’t take these keys from the unit settings. It uses the values from the table below.

The keys have the same meaning as the fields of the unit fuel settings. For the list of flags, see unit/get_fuel_settings. To replace invalid values with those calculated mathematically, add the 0x1000 flag to flags.

Specify minFillingVolume and minTheftVolume in the measurement system set in the mu key of the sensor: liters for SI (also used if mu isn’t specified), US gallons for US and metric with gallons, or imperial gallons for imperial. If the sensor has no fuel_params object, the measurement system of the unit is used.

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>
      }
    ],
    "ct": <uint>,       /* Creation time (Unix timestamp) */
    "mt": <uint>        /* Last modification time (Unix timestamp) */
  }
]

In Wialon Local, the ct and mt fields are available starting from version 2304.

The response to an update request doesn’t always show the changes. If the request changes only the name (n), description (d), or unit of measurement (m), the changes are saved, but the response contains the sensor as it was before the request, including the old mt value. If any other sensor property changes, the response contains the updated sensor. To get the current sensor properties, use the core/search_item request with the flag of sensors 0x00001000 (4096). In Wialon Local, this applies starting from version 2504. In earlier versions, the response always contains the updated sensor.

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.

If the sensor type (t) doesn’t exactly match one of the values listed in Sensor types, the request can return error 6 even though the sensor is already created, updated, or deleted. Don’t repeat a create request after this error, because each retry creates one more sensor. To check the result, get the unit sensors with the core/search_item request. In Wialon Local, this applies starting from version 2504. In earlier versions, the request is completed successfully in this case.