Geocoding and Address Entry¶
CoPilot has two distinct options for geocoding, which matches user input to actual locations on the map. These options are Type-ahead (autocomplete) and Classic.
This is the more commonly used option as it is the version displayed on the CoPilot screen. As the user starts to type an address, the available options are provided beneath the search box. Only the matching return values are shown. If a letter is entered that is not relevant, the last relevant search result or closest match is shown. The user first has to enter a city or postcode to allow further searches on streets within those locations, before finally entering a matching house number.
The user is not able to enter an address that is not within the CoPilot street database.
It is possible to use the SDK App or SDK Libraries APIs to recreate the type-ahead wizard within an integration application. This can be achieved with Msg_Search* (SDK App) and TypeAheadGeocoder (SDK Libraries).
Classic Geocoding is more commonly used via the integration options. It cannot be accessed via the CoPilot application user interface. Classic geocoding entries are passed as a complete string with country, postcode, city, street, and house number. Not all entries need to contain values, but a partial or misspelled entry will have a negative impact on search results. For example, if a postcode is provided that does not exist within the map data, this piece of information will be dropped and not used in the search.
It is possible to search for an address that does not exist in the CoPilot map database. This could be for numerous reasons – the address is new, the address name has changed or the area has not been digitally mapped.
Stops and Waypoints¶
What is a Stop?¶
A stop is a location the driver must reach. It should be as accurate as possible to ensure the best route is provided. To reach a stop, the driver must reach the street location that has been geocoded. Upon arrival, the driver will be informed of the side of the street where the location exists if CoPilot has been able to determine this information.
What is a Waypoint?¶
A waypoint is a route influencing point or a via point. This is not a stop the driver has to reach, but a location you would like to use to guide the driver to a stop. Waypoints are marked in the CoPilot trip list with an arrow.
Waypoints and RouteSync¶
Waypoints are not used in [RouteSync]/feature-guide/routesync/), which is designed to help ensure stricter route compliance and in-vehicle consistency from the back office. RouteSync is used to shape the exact roads the driver is to use, using many locations between the first and last stops. (Please see the section on RouteSync for additional information.)
When a waypoint has been set, the driver will need to reach a predefined straight line distance radius to activate the waypoint handling logic. This is a configurable value which can be set via the user.cfg file (WaypointRadius). The default value is set to 10 miles. If the driver never enters this radius, the waypoint will not be removed.
Once the driver enters this radius, CoPilot enables its waypoint monitoring logic. Each time the driver deviates from the route CoPilot will record the straight line distance. The distance from the current position to the next waypoint and to the following destination (this may be either another waypoint or a stop) will be recorded.
With each record taken, CoPilot will check to see if the driver is closer to the current waypoint than previous. If yes, then CoPilot assumes the driver is still trying to navigate toward the waypoint and all previously recorded distances are ignored, saving only this most recent deviation.
If the straight line distance to the current waypoint is increasing, then CoPilot saves this latest distance. Once three consecutive deviations occur and this distance is increasing, CoPilot will start the second stage of this logic.
For each new deviation, CoPilot will check the distance recorded to see if the delta from the first deviation in the list to the most recent deviation satisfies the logic. If it does, CoPilot will remove the waypoint from the trip and provide guidance to the next destination. If the next destination is a waypoint and the driver is not getting closer, once the delta between the driver and the waypoint grows to double the “WaypointDelta” the waypoint will be removed. The delta can be configured in "WaypointDelta" via the user.cfg file. (See below.)
If the driver simply continues toward the waypoint, it will be removed once the vehicle is within 0.2 miles.
Waypoint Configuration options¶
All values are stored in miles and defined in hundredths of miles. This allows for a small waypoint radius to be defined if desired.
All settings are saved in CoPilot user.cfg which can be amended manually or configured via SDK App using Msg_ConfigSetIntVal .
[User Settings] "WaypointRadius"=1000
10 miles - This defines the radius, in straight line miles, around the waypoint that the driver has to be inside to active CoPilot's waypoint handling logic.
[User Settings] "WaypointDelta"=500
5 miles - The distance a driver must travel, in straight line miles, both away from the current waypoint and towards the next destination (stop or waypoint).
[User Settings] "WaypointDeltaIgnoringNextDest"=1000
10 miles - This is the cutoff for if you’re not getting closer to your next destination, but you are getting further and further from your waypoint.
[User Settings] "WaypointDeviations"=3
3 - This is the number of deviations required to activate logic where we test your distances to determine waypoint removal.
SDK App Waypoint API¶
#define MSG_ID_GenericData 0xf1000115
#define MSG_IDT_TOGGLESTOPORWAYPOINT 0x0046L
Toggles stop to waypoint and vice versa. To be used with the Msg_TripAddStopWithHouseNum. Works when trip has more than 2 stops.
Request (MSG_IDT_ TOGGLESTOPORWAYPOINT):
· Pass lPayload = index of the stop
· Return value = 1
SDK Libraries Waypoint API¶
To build a waypoint using SDK Libraries, APIs use StopBuilder and call the setDestinationFlag method with a false parameter. This will build a waypoint instead of a regular destination.
Please manually amend the user.cfg values discussed above to change the default distance values for waypoint logic.