How to use itineraries

Itinerary is the powerful feature of the SDK.
Basically it defines a list of waypoints to be mandatorily visited during a journey.
Navigation over itinerary makes sure all waypoints are visited and the travel between waypoints is done in a most optimal way.
Itineraries are supported with 3 json oriented API functions: AddItinerary, SetRoute, GetRouteStatus.

Functions

• AddItinerary - adds a json itinerary into the navigation space ready for use, it is uniquely identified by a string name
• SetRoute - sets itinerary for navigation. The itinerary selection is given byt its name
• GetRouteStatus - retrieves json string giving status on itinerary execution, mainly information about ETA on each waypoint.

Itinerary waypoints

There are 3 types of waypoints:

• START - defines the starting point of the itinerary, where a car actually is or is anticipated to be. It is typically the depot. Please note it is not meant to be the first pickup or deliver point or a served customer.
• VIA - defines the place, which must be visited. It is typically the pickup/delivery point. The first VIA waypoint typically defines the first pickup/delivery point or a served customer.
• FINISH - defines the finish of the itinerary. It is typically a depot or the last pickup/delivery point or a served customer.

Actually there is no functional diference between VIA and FINISH except the visualization aspect on map.

Each waypoint defines several atributes, among them the most important are:

• lat/lon - the exact GPS position of the waypoint
• hitRadius - in meters defines the proximity considered the waypoint is visited. The proximity is defined in a distance projected on route (not an air distance)
• timeWindow - optional information defining the desired time for a visit. In case the ETA to waypoint is falling outside of the time window a warning appears
• stopDelay - expected time in seconds a driver will stay at the waypoint to e.g. to perform a service, so called service time

Itinerary format

Though itineraries basically define the list of waypoints, the itinerary format describes it through routeparts.
The routepart is the road segment delimited by two consecutive waypoints.
Example:
An itinerary having 3 waypoints START-VIA-FINISH contains 2 routeparts: 1. START to VIA (START-VIA) and 2. VIA to FINISH (VIA-FINISH)
An itinerary having 4 waypoints START-VIA1-VIA2-FINISH contains 3 routeparts: START-VIA1, VIA1-VIA2, VIA2-FINISH (shown in the picture bellow)

Each routepart thus defines a from-waypoint (WaypointFrom) and a to-waypoint (WaypointTo).
In effect, it means the WaypointTo of a routepart matches the WaypointFrom of a next routepart.

Please note that currently we do not support the discontinued itineraries, where the WaypointTo of a routepart does not match the WaypointFrom of a next routepart.
In case this match is violated in an itinerary the information of the WaypointFrom is ignored.
Because of this redundancy the format is relaxed so that the WaypointFrom does not have to be provided as it is inferred from the WaypointTo of a previous routepart.
Please note the exception is the WaypointFrom of the first routepart (see the section bellow).

The details of itinerary format are given in Itinerary format

Itinerary with or without START waypoint

There are two uses of itineraries, one which defines the START waypoint and one, which does not.
In the former case the START waypoint is defined (means anticipated or planned) and it means the call of SetRoute will immediately calculate the route even if there no GPS signal available.
Neverthless once the GPS signal (aka GPS fix) is available the START waypoint's GPS position is replaced with the actual GPS position and route towards the first VIA waypoint is recalculated. See the case on the picture bellow.

In the latter case without stating a START waypoint a route might not be calculated in case of GPS signal is not available since the start position is not known.
The SetRoute call might return an exception Waiting for Valid Signal, which means the route will get calculated only after the GPS fix oocurs.
Please note that even when there is no GPS fix the navigation keeps the so called last valid position and can use this as a starting point.

Itinerary execution

During the execution of an itinerary (means navigation) the visited waypoints (proximity of HitRadius) are denoted as visited opposed to the original state unvisited.
This status is obtained through the function GetRouteStatus.
Similarly the function reports per waypoint the information on ETA (estimated time arrival) or TA (time arrival).
Prior visiting the waypoint the function reports only the attribute ETA and after a visit it reports only the attribute TA.

Exception is the START waypoint, which is initially unvisited but becomes visited with GPS fix.
At the same time the GPS position of START is replaced with actual GPS position and a recalculation is immediately performed in case an actual GPS position does not match GPS defintion of the START waypoint.

Itinerary ETA calculation

ETA values on the unvisited waypoints are under constant recalculations.
ETA values are affected by delays caused by possible wrong driver detours, service time delays on waypoints, change of traffic state with e.g. occurence of traffic jams.
The following picture shows an example how ETA evolves during an itinerary execution.
Please note the ETD values are not retrievable from GetRouteStatus, but can be derived as the sum of ETA + stopDelay.
Please note the TD values are not retrievable from GetRouteStatus but can be obtained through an explicit driver operation (e.g. confirm button).

Itinerary update on the fly

Sometimes it can happen that during an itinerary execution (e.g on the 7 waypoints' itinerary 3 already visited) it is desired to change the setup of the remaining itinerary (the 4 downstream waypoints), e.g. because the situation has changed and a target customer sitting on the waypoint 6 will not be reachable.
In this case the management control should first check he actual state of the itinerary via the function GetRouteStatus, through which it will detect the number of unvisited waypoints.
And in the next step it will construct a new itinerary, which will only contain the remainder of the original itinerary, i.e. modified setup of the previosly unvisited 4 waypoints.
And it will reapply the functions AddItinerary and SetRoute.