Version 1.1 von YellowFox_RD am 2024/12/19 10:11
Zeige letzte Bearbeiter
1 (% class="box" %)
2 (((Inhaltsverzeichnis)))
3 {{toc/}}
4
5 Setzt den Kilometerstand für ein Fahrzeug.
6 = Beschreibung =
7 //**//(% class="green mark" %)GET(%%)// vehicle_settings/set_odometer.php?company**=COMPANY_RTIKEY**&vehicle**=VEHICLE_RTIKEY**&odometer**=ODOMETER//
8
9 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.
10 = Voraussetzungen und Beschränkungen =
11 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 werden. Prinzipiell sind diese Quellen für einen genauen Kilometerstand zu bevorzugen. Die Kilometerstandsquelle können Sie im Portal über die fahrzeugbezogenen Einstellungen setzen.
12 = Parameter =
13 |=Parameter|=Beschreibung|=Typ|=Hinweis|=Pflicht
14 |company|RTI Firmenschlüssel|string||ja
15 |vehicle|RTI Fahrzeugschlüssel|string||ja
16 |odometer|Kilometerstand|integer|Kilometerstand der gesetzt werden soll
17 Pflicht für die erste Anfrage|(ja)
18 |hash|Hash zur Bestätigung der Anfrage|string|Pflicht für die zweite Anfrage zu Bestätigung des Kilometerstandes|(ja)
19
20 = Rückgabe =
21 Es wird ein **string** zurückgegeben. Im Fehlerfall wird "(% class="error" %)**ERROR:Beschreibung**(%%)" zurückgegeben.
22 == Mögliche Fehlerwerte ==
23 |=Fehler|=Beschreibung
24 |MISSING_VEHICLE|Die Angabe des Fahrzeuges ist Pflicht.
25 |INVALID_FORMAT_ODOMETER|Es wurde ein Kilometerstand übermittelt, der nicht dem erwarteten Format entspricht. Der Kilometerstand muss eine Ganzzahl sein.
26 |CAN_NOT_PROCESS_HASH_AND_ODOMETER_AT_ONCE|Es wurde sowohl ein Hash, als auch ein Kilometerstand angegeben. Bitte geben Sie nur eines von beidem an.
27 |INCOMPLETE_REQUEST_PARAMS|Es wurde weder ein Hash, noch ein Kilometerstand angegeben. Bitte geben Sie eines von beiden mit.
28 |NOT_SUPPORTED_BY_VEHICLE|Das angegebene Fahrzeug unterstützt keine manuellen Kilometerstände. Das kann am Boxtyp liegen oder aber es ist eine andere Kilometerstandsquelle als GPS angegeben.
29 |LAST_SET_ODOMETER_LESS_THAN_10_MINUTES_AGO|Ein manueller Kilometerstand kann maximal alle 10 Minuten übermittelt werden.
30 |SET_COMMAND_ALREADY_IN_PROCESS|Ein manueller Kilometerstand befindet sich aktuell noch in der Warteschlange. Sie müssen warten, bis dieser Befehl verarbeitet wurde.
31 |INVALID_CURRENT_ODOMETER|Der 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.
32 |NEW_ODOMETER_CAN_NOT_BE_LESS_THAN_LAST_ODOMETER|Der neue Kilometerstand kann nicht niedriger als der letzte manuelle Kilometerstand sein.
33
34 == JSON ==
35 === Erklärung der Felder ===
36 |=Feld|=Beschreibung
37 |status|Mögiche Werte:
38 (((
39 * NEED_COMMIT: Der Kilometerstand wurde angegeben und erfolgreich validiert. Er muss noch bestätigt werden.
40 * OK: Der Kilometerstand wurde bestätigt und an die Box übermittelt.
41 )))
42 |queryDate|Wann wurde diese Anfrage übermittelt?
43 |odometer|(((
44 * current: Aktueller Kilometerstand laut Positionsmeldungen
45 * new: übermittelter Kilometerstand
46 )))
47 |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.
48 (((
49 * current: fester Korrekturfaktor der Box
50 * calculated: berechneter Korrekturfaktor um alle betroffenen Positionsmeldungen auf den gewünschten aktuellen Kilometerstand anzupassen 
51 * suggested: vorgeschlagener fester Korrekturfaktor auf Basis des aktuellen Faktors und des berechneten, um perspektivisch eine weitere Anpassung zu vermeiden
52 )))
53 |commandInfo|Infotext was passieren wird, wenn dieser Kilometerstand bestätigt wird. Es können 2 Fälle eintreten:
54 (((
55 * alle Meldungen zwischen der letzten und dieser Anpassung werden angepasst
56 * die letzte bekannte Meldung ist die letzte Anpassung - es müssen keine Positionsmeldungen angepasst werden, der Kilometerstand wird hart gesetzt
57 )))
58 |hash|Hash der übermittelt werden muss um die Anfrage zu bestätigen
59
60 === Beispiel ===
61 |=Rückgabe als JSON
62 |{
63     "status": "NEED_COMMIT ~| OK",
64     "queryDate": "2023-05-24T09:16:47+0200",
65     "odometer":
66     {
67         "current": 5015,
68         "new": 6000
69     },
70     "correctionFactor":
71     {
72         "current": 1,
73         "calculated": 1.1964107676969,
74         "suggested": 1.1964107676969
75     },
76     "commandInfo":
77     {
78         "status": 2,
79         "text": "Applying this odometer will change all position messages since last set odometer by the calculated correction factor."
80     },
81     "hash": "6DFB2C5F9A552C014135CBDAFD09CE81"
82 }
83
84 = Beispielaufrufe =
85 ==== Anfrage 1: Angabe Kilometerstand ====
86
87 {{code language="java"}}https://map.yellowfox.de/rti/vehicle_settings/set_odometer.php?company=COMPANY_RTIKEY&vehicle=VEHICLE_RTIKEY&odometer=12000
88
89 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{{/code}}
90
91 ==== Anfrage 2: Bestätigung des angegebenen Kilometerstands ====
92
93 {{code language="java"}}https://map.yellowfox.de/rti/vehicle_settings/set_odometer.php?company=COMPANY_RTIKEY&vehicle=VEHICLE_RTIKEY&hash=3785678916
94
95 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{{/code}}
96