Entering Stops

Geocoding and Address Entry

CoPilot has two distinct options for entering addresses for geocoding, which matches user input to actual locations on the map. These options are Type-ahead (autocomplete) and Classic.

Type-ahead Geocoding

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 CPIK libraries APIs to recreate the type-ahead wizard within an integration application. This can be achieved with Msg_Search* (SDK App) and TypeAheadGeocoder (CPIK libraries).

Classic Geocoding

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, sometimes referred to as a “via” point. A waypoint modifies the route path so it passes through a specified point, without acting as a full stop for a pickup, a delivery, or a rest break.

Waypoints are generally used if you want to guide the route along desired roads or through desired areas, but don’t have any work stops in those areas. For example, if a waypoint is entered as a city or a town, the route will travel through the center of the city or town. If it is entered as a specific address or longitude/latitude point, the route will pass directly by that location. Waypoints are marked in the CoPilot trip list with an arrow.

When CoPilot calculates the route path, it will pass directly by the waypoint, as if it were a stop. However, CoPilot includes logic that removes a waypoint from the trip list if a driver passes the waypoint within a certain distance.

Waypoints and RouteSync

Waypoints are not used in 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.)

Waypoint Logic

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 product.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 product.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’s product.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 MSG_IDT_TOGGLESTOPORWAYPOINT

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

Response (MSG_IDT_TOGGLESTOPORWAYPOINT):

· Return value = 1

To amend the default distance values for waypoint logic please use Msg_ConfigSetIntVal and Msg_ConfigGetIntVal APIs.

CPIK Libraries Waypoint API

To build a waypoint using CPIK 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 product.cfg values discussed above to change the default distance values for waypoint logic.