Last modified by YellowFox_RD on 2025/01/23 09:54
From version 2.1
edited by Dominic Lippmann
on 2025/01/23 09:53
Change comment: There is no comment for this version
To version 1.1
edited by YellowFox_RD
on 2024/12/19 10:11
Change comment: Imported from XAR

Summary

Details

Page properties
Author
... ... @@ -1,1 +1,1 @@
1 -XWiki.yf-dominic
1 +XWiki.YellowFox_RD
Content
... ... @@ -1,37 +1,25 @@
1 1  (% class="box" %)
2 -(((
3 -Table of Contents
4 -)))
5 -
2 +(((Table of Contents)))
6 6  {{toc/}}
7 7  
8 8  Set the current odometer of a vehicle.
9 -
10 10  = Description =
7 +//**//(% class="green mark" %)GET(%%)// vehicle_settings/set_odometer.php?company**=COMPANY_RTIKEY**&vehicle**=VEHICLE_RTIKEY**&odometer**=ODOMETER//
11 11  
12 -(% class="green mark" %)**GET**(%%)**// vehicle_settings/set_odometer.php?company//**//=COMPANY_RTIKEY**&vehicle**=VEHICLE_RTIKEY**&odometer**=ODOMETER//
13 -
14 14  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.
15 -
16 16  = Requirements and restrictions =
17 -
18 -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.
19 -
11 +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. 
20 20  = Parameter =
21 -
22 22  |=Parameter|=description|=type|=hint|=mandatory
23 -|company|RTI company key|string| |yes
24 -|vehicle|RTI vehicle key|string| |yes
14 +|company|RTI company key|string||yes
15 +|vehicle|RTI vehicle key|string||yes
25 25  |odometer|odometer value|integer|Odometer value that should be set.
26 26  Is mandatory for first request.|(yes)
27 27  |hash|Hash to confirm the request.|string|Mandatory for the second request to confirm the request.|(yes)
28 28  
29 29  = Return value =
30 -
31 31  A **string** string will be returned . On error "(% class="error" %)**ERROR:description**(%%)" will be returned.
32 -
33 33  == Possible error values ==
34 -
35 35  |=Fehler|=Beschreibung
36 36  |MISSING_VEHICLE|Vehicle parameter is mandatory.
37 37  |INVALID_FORMAT_ODOMETER|The submitted odometer value does not match the expected format. It has to be an integer.
... ... @@ -44,11 +44,10 @@
44 44  |NEW_ODOMETER_CAN_NOT_BE_LESS_THAN_LAST_ODOMETER|The new odometer value can not be lower than the last manual value.
45 45  
46 46  == JSON ==
47 -
48 48  === Description of fields ===
49 -
50 50  |=field|=description
51 -|status|Possible values:(((
37 +|status|Possible values:
38 +(((
52 52  * NEED_COMMIT: The odometer value has been submitted and was validated successfully. It still has to be confirmed.
53 53  * OK: The odometer value has been confirmed and was sent to the box.
54 54  )))
... ... @@ -57,12 +57,14 @@
57 57  * current: current odometer according to position messages
58 58  * new: submitted odometer value
59 59  )))
60 -|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.(((
47 +|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.
48 +(((
61 61  * current: fixed correction factor of box
62 62  * calculated: calculated correction factor to adjust all affected position messages to submitted manual odometer value
63 63  * suggested: suggested correction factor based on the current and calculated factor to avoid further manual odometer values
64 64  )))
65 -|commandInfo|Info what will happen if you submit this odometer value. Two cases are possible:(((
53 +|commandInfo|Info what will happen if you submit this odometer value. Two cases are possible:
54 +(((
66 66  * all messages since the last manual entry will be adjusted
67 67  * the last known message is the last manual entry - there are no position messages to be adjusted, the odometer value will be just set
68 68  )))
... ... @@ -69,42 +69,38 @@
69 69  |hash|hash that has to be sent for confirm request
70 70  
71 71  === Example ===
72 -
73 73  |=Return as JSON
74 74  |{
75 - "status": "NEED_COMMIT ~| OK",
76 - "queryDate": "2023-05-24T09:16:47+0200",
77 - "odometer":
78 - {
79 - "current": 5015,
80 - "new": 6000
81 - },
82 - "correctionFactor":
83 - {
84 - "current": 1,
85 - "calculated": 1.1964107676969,
86 - "suggested": 1.1964107676969
87 - },
88 - "commandInfo":
89 - {
90 - "status": 2,
91 - "text": "Applying this odometer will change all position messages since last set odometer by the calculated correction factor."
92 - },
93 - "hash": "6DFB2C5F9A552C014135CBDAFD09CE81"
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"
94 94  }
95 95  
96 96  = Example calls =
85 +==== Request 1: Submit odometer value ====
97 97  
98 -== Request 1: Submit odometer value ==
87 +{{code language="java"}}https://map.yellowfox.de/rti/vehicle_settings/set_odometer.php?company=COMPANY_RTIKEY&vehicle=VEHICLE_RTIKEY&odometer=12000
99 99  
100 -{{code language="java"}}
101 -https://map.yellowfox.de/rti/vehicle_settings/set_odometer.php?company=COMPANY_RTIKEY&vehicle=VEHICLE_RTIKEY&odometer=12000
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}}
102 102  
103 -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
104 -{{/code}}
91 +==== Request 2: Confirm odometer value ====
105 105  
106 -== Request 2: Confirm odometer value ==
107 -
108 108  {{code language="java"}}https://map.yellowfox.de/rti/vehicle_settings/set_odometer.php?company=COMPANY_RTIKEY&vehicle=VEHICLE_RTIKEY&hash=3785678916
109 109  
110 110  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}}