Set the current odometer of a vehicle.

Description

GET vehicle_settings/set_odometer.php?company=COMPANY_RTIKEY&vehicle=VEHICLE_RTIKEY&odometer=ODOMETER


This function is a 2-step call. First you have to send the desired odometer value. The system will validate this and returns the calculated correction factor and a hash for confirmation. This hash has to be returned during the following 5 minutes to confirm the changes and send them to the box.

Requirements and restrictions

A manual set odometer is supported by all boxtypes, which are able to track odometer values based on GPS. This includes the YellowTracker 100 to 620, as well as the YellowTracker mobile Xtreme. Vehicles imported by OEM interfaces or mobile apps are not included. Some boxtypes support odometer values imported via Digitacho or Squarell. If such a box has set its odometer source to something else than GPS, you will not be able to set a manual odometer value. These odometer sources should be preferred for getting precise odometer values. You can change the odometer source at the portal at vehicle-based settings. 

Parameter

Parameterdescriptiontypehintmandatory
companyRTI company keystring
yes
vehicleRTI vehicle keystring
yes
odometerodometer valueinteger

Odometer value that should be set.

Is mandatory for first request.

(yes)
hashHash to confirm the request.stringMandatory for the second request to confirm the request.(yes)

Return value

A string string will be returned . On error "ERROR:description" will be returned.

Possible error values

FehlerBeschreibung
MISSING_VEHICLEVehicle parameter is mandatory.
INVALID_FORMAT_ODOMETERThe submitted odometer value does not match the expected format. It has to be an integer.
CAN_NOT_PROCESS_HASH_AND_ODOMETER_AT_ONCEYou have submitted a hash as well as an odometer value. Please enter only one.
INCOMPLETE_REQUEST_PARAMSYou have neither submitted a hash, nor an odometer value. Please enter one of these.
NOT_SUPPORTED_BY_VEHICLEThe given vehicle does not support manual set odometer values. This might be due to its boxtype or the odometer source is something else than GPS.
LAST_SET_ODOMETER_LESS_THAN_10_MINUTES_AGOA new manual odometer value can only be submitted every 10 minutes.
SET_COMMAND_ALREADY_IN_PROCESSA manual odometer value is still waiting in queue. You have to wait until it's processed.
INVALID_CURRENT_ODOMETERThe current odometer value of the vehicle is invalid. This means that it's lower than the last manual odometer value. It probably has not been moved since last manual odometer value. We need a first position message to finish the last manual odometer value request.
NEW_ODOMETER_CAN_NOT_BE_LESS_THAN_LAST_ODOMETERThe new odometer value can not be lower than the last manual value.

JSON

Description of fields

fielddescription
status

Possible values:

  • NEED_COMMIT: The odometer value has been submitted and was validated successfully. It still has to be confirmed.
  • OK: The odometer value has been confirmed and was sent to the box.
queryDateWhen was this request sent?
odometer
  • current: current odometer according to position messages
  • new: submitted odometer value
correctionFactor

GPS as the source for odometer values can lead to differences from the actual odometer value. The correction factor indicates how much the measured odometer values should be stretched to compensate the offset. Each box has a fixed correction factor which is applied to each position message. Changing the odometer value does also apply a correction factor to each affected position message.

  • current: fixed correction factor of box
  • calculated: calculated correction factor to adjust all affected position messages to submitted manual odometer value
  • suggested: suggested correction factor based on the current and calculated factor to avoid further manual odometer values
commandInfo

Info what will happen if you submit this odometer value. Two cases are possible:

  • all messages since the last manual entry will be adjusted
  • the last known message is the last manual entry - there are no position messages to be adjusted, the odometer value will be just set
hashhash that has to be sent for confirm request

Example

Return as JSON

{

    "status": "NEED_COMMIT | OK",

    "queryDate": "2023-05-24T09:16:47+0200",

    "odometer":

    {

        "current": 5015,

        "new": 6000

    },

    "correctionFactor":

    {

        "current": 1,

        "calculated": 1.1964107676969,

        "suggested": 1.1964107676969

    },

    "commandInfo":

    {

        "status": 2,

        "text": "Applying this odometer will change all position messages since last set odometer by the calculated correction factor."

    },

    "hash": "6DFB2C5F9A552C014135CBDAFD09CE81"

}

Example calls

Request 1: Submit odometer value

https://map.yellowfox.de/rti/vehicle_settings/set_odometer.php?company=COMPANY_RTIKEY&vehicle=VEHICLE_RTIKEY&odometer=12000

https://map.yellowfox.de/rti/vehicle_settings/set_odometer.php?company=COMPANY_RTIKEY&vehicle={"type":"car_ident","groupKey":"GROUP_RTIKEY","ident":"VEHICLE_IDENT"}&odometer=12000

Request 2: Confirm odometer value

https://map.yellowfox.de/rti/vehicle_settings/set_odometer.php?company=COMPANY_RTIKEY&vehicle=VEHICLE_RTIKEY&hash=3785678916

https://map.yellowfox.de/rti/vehicle_settings/set_odometer.php?company=COMPANY_RTIKEY&vehicle={"type":"car_ident","groupKey":"GROUP_RTIKEY","ident":"VEHICLE_IDENT"}&hash=3785678916



  • No labels