Versions Compared

Old Version 7

changes.mady.by.user YellowFox R&D

Saved on

compared with

New Version 8

changes.mady.by.user YellowFox R&D

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Sv translation
languagede

Setzt den Kilometerstand für ein Fahrzeug.

Beschreibung

Status
colourGreen
titleGET
vehicle_settings/set_odometer.php?company=COMPANY_RTIKEY&vehicle=VEHICLE_RTIKEY&odometer=ODOMETER


Bei dieser Funktion handelt es sich um einen zweistufigen Aufruf. Es muss zunächst der gewünschte Kilometerstand geschickt werden. Das System validiert daraufhin diese Eingabe und gibt den berechneten Korrekturfaktor und einen Hash zu Bestätigung zurück. Dieser Hash muss innerhalb der nächsten 5 Minuten zurückgeschickt werden, um die Änderung zu bestätigen und den Kilometerstand an die Box zu übermitteln.

Voraussetzungen und Beschränkungen

Ein manuell gesetzter Kilometerstand wird grundlegend von allen Boxen unterstützt, die in der Lage sind, GPS-basiert einen Kilometerstand zu erfassen. Dazu gehören YellowTracker 100 bis 620, sowie auch der YellowTracker mobile Xtreme. Ausgeschlossen sind OEM Anbindungen oder auch Mobile Apps. Einige Boxen unterstützen auch eine Kilometerstandserfassung über Digitacho oder Squarell. Wurde bei solch einer Box die Kilometerstandsquelle auf etwas anderes als GPS gesetzt, so kann kein manueller Kilometerstand mehr gesetzt werde. Prinzipiell sind diese Quellen für einen genauen Kilometerstand zu bevorzugen. Die Kilometerstandsquelle können Sie im Portal über die fahrzeugbezogenen Einstellungen setzen.

Parameter

ParameterBeschreibungTypHinweisPflicht
companyRTI Firmenschlüsselstring
ja
vehicleRTI Fahrzeugschlüsselstring
ja
odometerKilometerstandinteger

Kilometerstand der gesetzt werden soll

Pflicht für die erste Anfrage

(ja)
hashHash zur Bestätigung der AnfragestringPflicht für die zweite Anfrage zu Bestätigung des Kilometerstandes(ja)

Rückgabe

Es wird ein string zurückgegeben. Im Fehlerfall wird "ERROR:Beschreibung" zurückgegeben.

Mögliche Fehlerwerte

FehlerBeschreibung
MISSING_VEHICLEDie Angabe des Fahrzeuges ist Pflicht.
INVALID_FORMAT_ODOMETEREs wurde ein Kilometerstand übermittelt, der nicht dem erwarteten Format entspricht. Der Kilometerstand muss eine Ganzzahl sein.
CAN_NOT_PROCESS_HASH_AND_ODOMETER_AT_ONCEEs wurde sowohl ein Hash, als auch ein Kilometerstand angegeben. Bitte geben Sie nur eines von beidem an.
INCOMPLETE_REQUEST_PARAMSEs wurde weder ein Hash, noch ein Kilometerstand angegeben. Bitte geben Sie eines von beiden mit.
NOT_SUPPORTED_BY_VEHICLEDas angegebene Fahrzeug unterstützt keine manuellen Kilometerstände. Das kann am Boxtyp liegen oder aber es ist eine andere Kilometerstandsquelle als GPS angegeben.
LAST_SET_ODOMETER_LESS_THAN_10_MINUTES_AGOEin manueller Kilometerstand kann maximal alle 10 Minuten übermittelt werden.
SET_COMMAND_ALREADY_IN_PROCESSEin manueller Kilometerstand befindet sich aktuell noch in der Warteschlange. Sie müssen warten, bis dieser Befehl verarbeitet wurde.
INVALID_CURRENT_ODOMETERDer aktuelle Kilometerstand des Fahrzeuges ist invalide. Das heißt, dass er niedriger ist, als die letzte manuelle Anpassung. Wahrscheinlich hat sich das Fahrzeug seitdem noch nicht wieder bewegt. Erst mit der ersten Positionsmeldung wurde der letzte Angleich vollständig verarbeitet.
NEW_ODOMETER_CAN_NOT_BE_LESS_THAN_LAST_ODOMETERDer neue Kilometerstand kann nicht niedriger als der letzte manuelle Kilometerstand sein.


JSON

Erklärung der Felder

FeldBeschreibung
status

Mögiche Werte:

  • NEED_COMMIT: Der Kilometerstand wurde angegeben und erfolgreich validiert. Er muss noch bestätigt werden.
  • OK: Der Kilometerstand wurde bestätigt und an die Box übermittelt.
queryDateWann wurde diese Anfrage übermittelt?
odometer
  • current: Aktueller Kilometerstand laut Positionsmeldungen
  • new: übermittelter Kilometerstand
correctionFactor

GPS Ortung als Quelle für den Kilometerstand kann zu Abweichungen gegenüber dem realen Kilometerstand führen. Der Korrekturfaktor gibt an, um viel der Kilometerstand automatisch gestreckt/gestaucht wird, um Abweichungen langfristig entgegen zu wirken. Jede Box besitzt einen festen Korrekturfaktor, welcher mit jeder Positionsmeldung verrechnet wird. Eine Anpassung des Kilometerstandes verrechnet die aufgezeichneten Kilometerstände ebenfalls mit einem Korrekturfaktor um die Meldungen gleichmäßig anzupassen.

  • current: fester Korrekturfaktor der Box
  • calculated: berechneter Korrekturfaktor um alle betroffenen Positionsmeldungen auf den gewünschten aktuellen Kilometerstand anzupassen 
  • suggested: vorgeschlagener fester Korrekturfaktor auf Basis des aktuellen Faktors und des berechneten, um perspektivisch eine weitere Anpassung zu vermeiden
commandInfo

Infotext was passieren wird, wenn dieser Kilometerstand bestätigt wird. Es können 2 Fälle eintreten:

  • alle Meldungen zwischen der letzten und dieser Anpassung werden angepasst
  • die letzte bekannte Meldung ist die letzte Anpassung - es müssen keine Positionsmeldungen angepasst werden, der Kilometerstand wird hart gesetzt
hashHash der übermittelt werden muss um die Anfrage zu bestätigen


Beispiel

Rückgabe als 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"

}

Beispielaufrufe

Anfrage 1: Angabe Kilometerstand

Code Block
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

Anfrage 2: Bestätigung des angegebenen Kilometerstands

Code Block
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



Sv translation
languageen

Set the current odometer of a vehicle.

Description

Status
colourGreen
titleGET
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

Code Block
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

Code Block
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