Wiki source code of vehicle_settings/set_odometer.php
Last modified by YellowFox_RD on 2025/01/23 09:54
Hide last authors
| author | version | line-number | content |
|---|---|---|---|
 |
1.1 | 1 | (% class="box" %) |
| |
2.1 | 2 | ((( |
| 3 | Table of Contents | ||
| 4 | ))) | ||
| 5 | |||
| |
1.1 | 6 | {{toc/}} |
| 7 | |||
| |
2.1 | 8 | Set the current odometer of a vehicle. |
| |
1.1 | 9 | |
| |
2.1 | 10 | = Description = |
| 11 | |||
| 12 | (% class="green mark" %)**GET**(%%)**// vehicle_settings/set_odometer.php?company//**//=COMPANY_RTIKEY**&vehicle**=VEHICLE_RTIKEY**&odometer**=ODOMETER// | ||
| 13 | |||
| 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 | = 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 | |||
| |
1.1 | 20 | = Parameter = |
| 21 | |||
| |
2.1 | 22 | |=Parameter|=description|=type|=hint|=mandatory |
| 23 | |company|RTI company key|string| |yes | ||
| 24 | |vehicle|RTI vehicle key|string| |yes | ||
| 25 | |odometer|odometer value|integer|Odometer value that should be set. | ||
| 26 | Is mandatory for first request.|(yes) | ||
| 27 | |hash|Hash to confirm the request.|string|Mandatory for the second request to confirm the request.|(yes) | ||
| 28 | |||
| 29 | = Return value = | ||
| 30 | |||
| 31 | A **string** string will be returned . On error "(% class="error" %)**ERROR:description**(%%)" will be returned. | ||
| 32 | |||
| 33 | == Possible error values == | ||
| 34 | |||
| |
1.1 | 35 | |=Fehler|=Beschreibung |
| |
2.1 | 36 | |MISSING_VEHICLE|Vehicle parameter is mandatory. |
| 37 | |INVALID_FORMAT_ODOMETER|The submitted odometer value does not match the expected format. It has to be an integer. | ||
| 38 | |CAN_NOT_PROCESS_HASH_AND_ODOMETER_AT_ONCE|You have submitted a hash as well as an odometer value. Please enter only one. | ||
| 39 | |INCOMPLETE_REQUEST_PARAMS|You have neither submitted a hash, nor an odometer value. Please enter one of these. | ||
| 40 | |NOT_SUPPORTED_BY_VEHICLE|The 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. | ||
| 41 | |LAST_SET_ODOMETER_LESS_THAN_10_MINUTES_AGO|A new manual odometer value can only be submitted every 10 minutes. | ||
| 42 | |SET_COMMAND_ALREADY_IN_PROCESS|A manual odometer value is still waiting in queue. You have to wait until it's processed. | ||
| 43 | |INVALID_CURRENT_ODOMETER|The 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. | ||
| 44 | |NEW_ODOMETER_CAN_NOT_BE_LESS_THAN_LAST_ODOMETER|The new odometer value can not be lower than the last manual value. | ||
| |
1.1 | 45 | |
| 46 | == JSON == | ||
| |
2.1 | 47 | |
| 48 | === Description of fields === | ||
| 49 | |||
| 50 | |=field|=description | ||
| 51 | |status|Possible values:((( | ||
| 52 | * NEED_COMMIT: The odometer value has been submitted and was validated successfully. It still has to be confirmed. | ||
| 53 | * OK: The odometer value has been confirmed and was sent to the box. | ||
| |
1.1 | 54 | ))) |
| |
2.1 | 55 | |queryDate|When was this request sent? |
| |
1.1 | 56 | |odometer|((( |
| |
2.1 | 57 | * current: current odometer according to position messages |
| 58 | * new: submitted odometer value | ||
| |
1.1 | 59 | ))) |
| |
2.1 | 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.((( |
| 61 | * current: fixed correction factor of box | ||
| 62 | * calculated: calculated correction factor to adjust all affected position messages to submitted manual odometer value | ||
| 63 | * suggested: suggested correction factor based on the current and calculated factor to avoid further manual odometer values | ||
| |
1.1 | 64 | ))) |
| |
2.1 | 65 | |commandInfo|Info what will happen if you submit this odometer value. Two cases are possible:((( |
| 66 | * all messages since the last manual entry will be adjusted | ||
| 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 | ||
| |
1.1 | 68 | ))) |
| |
2.1 | 69 | |hash|hash that has to be sent for confirm request |
| |
1.1 | 70 | |
| |
2.1 | 71 | === Example === |
| |
1.1 | 72 | |
| |
2.1 | 73 | |=Return as JSON |
| 74 | |{{code language="java"}}{ | ||
| 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" | ||
| 94 | }{{/code}} | ||
| |
1.1 | 95 | |
| |
2.1 | 96 | = Example calls = |
| |
1.1 | 97 | |
| |
2.1 | 98 | == Request 1: Submit odometer value == |
| |
1.1 | 99 | |
| |
2.1 | 100 | {{code language="java"}} |
| 101 | https://map.yellowfox.de/rti/vehicle_settings/set_odometer.php?company=COMPANY_RTIKEY&vehicle=VEHICLE_RTIKEY&odometer=12000 | ||
| |
1.1 | 102 | |
| |
2.1 | 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}} | ||
| 105 | |||
| 106 | == Request 2: Confirm odometer value == | ||
| 107 | |||
| |
1.1 | 108 | {{code language="java"}}https://map.yellowfox.de/rti/vehicle_settings/set_odometer.php?company=COMPANY_RTIKEY&vehicle=VEHICLE_RTIKEY&hash=3785678916 |
| 109 | |||
| 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}} | ||
| 111 |