RouteSync is a licensed CoPilot add-on feature that helps businesses maintain stricter route compliance and in-vehicle consistency by sending routes planned on back-office systems directly to a driver’s device.
RouteSync passes predefined locations (latitude/longitude coordinates or addresses) of the planned route into CoPilot on the mobile device. CoPilot will then generate the route following the locations and provide feedback with out-of-route notifications.
RouteSync can be integrated with CoPilot through the PC*MILER application, and also through the CoPilot SDK App or SDK Libraries by receiving routes pre-planned via your existing back office route planning systems. This document focuses on RouteSync via back office route planning systems.
Typical Uses of RouteSync¶
RouteSync is designed for routes that require a specific route path to be followed between each stop—whether or not that path matches standard CoPilot routing. Common uses include:
Long-haul or local trucking routes, where the origin, destination and intermediate stops for pickups and deliveries are set—with limited changes after dispatch—and you want to make sure the driver follows specific roads between the stops.
School bus routes, where the pick-ups or drop-offs are set, and you want the driver to follow a specific planned route between those points.
Other use cases are possible, but might require special configurations for the best user experience. These can include:
Municipal or utility routes that often involve circling around the same block or doubling back along the same road—with what is a seemingly very inefficient route between a very small number of stops.
Post, parcel, courier, and expedited routes where a large stop list can change frequently throughout the day, requiring repeated delivery of updated RouteSync routes.
How Does RouteSync Work?¶
When CoPilot receives a RouteSync input list for the roads you wish the driver to follow, it generates its own planned route, adhering to any road restrictions for the vehicle routing profile. It will use the first and last locations as the beginning and end of the trip, before comparing the planned route with the required route and ensuring all locations are successfully passed.
Ensuring Route Compliance¶
The first task is to ensure that the back office route matches the CoPilot-generated route. This requires a series of predefined locations, which can be passed as latitude/longitudes or addresses into CoPilot for route generation and verification.
Levels of Route Compliance¶
The level of route compliance included with a managed route sent to CoPilot indicates how strictly CoPilot should try to return to the original (sent) route in the event that the driver is out-of-route. The three possible compliance levels are:
Strict: CoPilot will try to navigate back to the original route at all costs, even if it means the driver needs to turn around and drive back to re-join the prescribed route.
Moderate: CoPilot will try to navigate back to the original route but will take into account the driver’s current position; i.e. CoPilot will try to rejoin the prescribed route as it navigates towards the destination, but along a route that is more reasonable than the Strict compliance level would follow.
Minimal: The original prescribed route is not taken into consideration. The new route planned may still rejoin the original route, but its first objective is to navigate to the destination from the driver’s current position. If the driver does re-join the original route, CoPilot will continue as previously planned.
RouteSync Input Requirements¶
The optimum number of defined locations will vary based upon your route strictness requirements and data allowance. In general, more points will achieve a more accurate match to your desired route. A few recommendations:
Ensure at least one latitude and longitude location for every road you wish to drive, and an additional latitude and longitude on each side of every turning junction. (For example, if the vehicle is heading south on 1st Avenue and then east on Main Street, include a point just to the north of that intersection, and one just to the east of that intersection.)
In urban areas, we recommend passing a greater number points—one point per road link for the greatest accuracy. A road link is a section of road between two intersections.
Locations can be farther apart when using motorways and highways. When including points on highways, it’s best to keep them away from exits and intersections so that CoPilot can select the proper ramp.
If RouteSync is not achieving the desired route, additional configuration settings are available that can improve results. Contact your Sales Engineer or submit a ticket to our Technical Support team by clicking the Tickets button at the top of the CoPilot Support Center.
RouteSync can accept multiple trip stops. The full input format for the JSON file can be found in the SDK App or SDK Libraries API documentation. Technical details are provided on the specific requirements for the files.
Out of Route¶
If the driver doesn’t follow the planned route and deviates onto another road, CoPilot can provide a notification to the client application that the driver is no longer on the planned route. The notification includes latitude, longitude, UTC time and UTC date as well as city, state or country.
Once the driver returns to the route, another notification will be provided, including the distance the user has driven since leaving the route. Notifications will also be provided each time the driver leaves and rejoins the planned route. Once the driver reaches the final destination, a notification for total distance out of route will be provided.
The defined APIs make it possible to set a distance off the planned route the driver is allowed to deviate before a notification alert is generated. The default value within CoPilot is 0.2 miles.
Managed and Unmanaged Route Options¶
There may be instances when you only wish to have part of the route managed. For example, a situation where navigating from the current location is not important but once the driver reaches the city, it is very important to use specific roads to reach the destination. In this instance, it is possible to have a partially managed route.
With each route that is passed into CoPilot, if the first location is greater than 5 miles from the current GPS position, CoPilot will navigate the user to the first location not under managed conditions. Therefore, if the driver is to leave this initial part of the route:
- There will be no notification as out of route.
- The route guidance will not follow any strict route recalculations to return until the beginning of the managed route section.
What happens when the pre-planned route drives via a road CoPilot believes is restricted? (e.g. A height restriction that conflicts with the vehicle size.)
CoPilot will generate the route requested ignoring the road restrictions. But once navigation begins CoPilot would provide its normal notifications and warnings, as necessary. These alerts are available on screen to the driver and via the SDK App or SDK Libraries API calls.
If the route planned takes the driver onto a road CoPilot believes is unsafe to provide guidance – for instance, the height-restricted road when the vehicle dimensions are greater – CoPilot will stop all audio and visual guidance for the duration of the restricted road. This is how CoPilot would behave in standard routing situations.
Route Calculation Times¶
Route calculation times are always complex to define. The first CoPilot action after receiving the pre-planned route is to generate its own route and run a comparison between the two. If the pre-planned route follows the CoPilot-generated route, the time taken to provide results will be quicker compared to when the route planned is significantly different.
Restricting CoPilot Interaction¶
During navigation, it is possible via the SDK App or SDK Libraries to lock CoPilot menu items. This restricts the user from overwriting the route, changing the routing profile, etc. Without this lock enabled, it is possible for the driver to remove the pre-planned route so no out-of-route notifications will be sent. Once the lock has been passed, it is only possible for the driver to change views between 2D, 3D and Directions.
Cancelling or Declining the Route¶
It is not possible for the driver to cancel or decline a route that has been passed into CoPilot. This can only be controlled via the integrating application. To replace a planned route, simply send another RouteSync message. This will erase and overwrite the existing route. To cancel RouteSync via the SDK App or SDK Libraries, you can pass in a new final destination or simply a blank destination to completely erase.
If CoPilot exits prior to the driver reaching the destination, the route planned is saved and will be continued when CoPilot relaunches. Out-of-route mileage for any driving completed between the exit and relaunch will not be recorded.
RouteSync and Traffic¶
Traffic will only affect the planned route if using vehicle type Auto with profile set to Quickest route. When the vehicle type for Truck is set, the CoPilot routing algorithm should not attempt to optimize the travel time.
Known Cases CoPilot will not Follow the Planned Route¶
RouteSync will follow the route as planned in almost all situations, but there are cases we know do not follow the RouteSync points. Most of these cases are not real situations, but are often seen when creating demo routes to test RouteSync:
If the start and end destination are on the same road link or within 0.1 miles of each other, but the route is planned to drive off the road link and around a significant detour to reach the destination. If the destination is too close, the RouteSync points will be ignored.
Multiple loops around a roundabout before taking the 1st exit.
Multiple legs back and forth across the same stretch of road. If this is required, a destination will need to be placed on either side to force the route.
Routes that require use of roads/foot paths that are not suitable for the vehicle routing profile. See the section on “Route Conflicts.”
RouteSync APIs for CoPilot SDK App¶
The following APIs can be used to send RouteSync Routes to CoPilot SDK App. Further details on all of these different functions can be found within the SDK App API documentation.
PC*MILER Generated RouteSync File
Non-PC*MILER integrations to send RouteSync route:
Universal API to receive points included within the input but not on the CoPilot route:
When RouteSync Routes are sent to CoPilot, routing notifications are sent back via API calls. These calls can be split into route calculations, road restrictions and when the destination has been reached.
Reaching the destination:
These notifications will be received providing the configuration settings noted below have been enabled. These settings require a value =1 within the user.cfg to receive the notifications.
[SDK] "RestrictedRoutingEvent"=1 "TripRoutingEvent"=1
When a RouteSync route has been sent to CoPilot, the user interface can be locked to prevent driver interaction. This can be carried out by using the following API commands. This is not a required step and is not restricted for use with RouteSync functionality.
RouteSync APIs for SDK Libraries¶
The following APIs can be used to send RouteSync routes to CoPilot SDK Libraries deployments. This will allow for the sending of routes as well as call backs and notifications.
PC*MILER Generated RouteSync File
Non-PC*MILER integrations to send RouteSync route
Monitoring CoPilot Routing Notifications
Along with RouteSync APIs, there are a number of user configuration options that will dictate the behavior of CoPilot when using RouteSync. These configurations are included below:
- To allow more granular routes to be generated, CoPilot will execute a second processing of the data.
- To disable the audio announcement. Default=true
- This user.cfg value will enable/disable the processing of routes received via RouteSync, when set to 0 will not allow RouteSync messages. Default=true. Please note when disabled and a file is sent to CoPilot you will still get the file received callback but the file will not be processed.
[User Settings] "RouteSyncEnabled"=0
RouteSync Popup messages
- This user.cfg setting will enable/disable RouteSync popup messages.
default = 0 CoPilot will show a pop-up message to the driver warning when a new RouteSync message has been received. A spinning loading icon will be displayed once the user has interacted with the pop-up message.
= 1 CoPilot will not pop-up a message to the driver when new RouteSync messages are received. The route will be automatically accepted. The screen will display a spinning loading icon once the input file has loaded.
= 2 CoPilot will not pop-up a message to the driver when new RouteSync messages are received, the screen will display a spinning loading icon before the route preview itinerary screen is displayed to the driver.
[User Settings] "RouteSyncPopup"=0
- This value is used to determine if CoPilot will navigate to the first stop on the RouteSync file or to the closest point on the route from the current GPS location.
This is a distance in miles. If the driver's current location is within this distance and the first stop, they will be taken to the closest point on the route. If the distance between the current location and the first stop is greater than this distance, the driver will be navigated to the first stop on the RouteSync route.
[User Settings] "RouteSyncOriginMilesDelta"=5
- To disable the above feature and always be routed to the closest point on the RouteSync route, RouteSyncReplaceFirstStop should be set to 0.
[User Settings] "RouteSyncReplaceFirstStop"=0
- If set to 1 this will replace the first stop (origin) of the RouteSync route with the driver’s current location.
[User Settings] "RouteSyncReplaceFirstStop"=1
CoPilot Process for Receiving and Processing a RouteSync Route
Once a RouteSync route has been passed to CoPilot by the integrated application, logic will be followed to inform the user of the different stages in the process. Notifications will be provided through a series of pop-up options and visual displays within the CoPilot UI.
- Once the RouteSync file has been sent to CoPilot, CoPilot will provide a pop-up notification informing the user that a route has been received.
- Once the notification is dismissed, the UI will be returned to the navigation screen. If a destination had already been set, guidance will continue to be provided. Users will be restricted from changing this destination or adding a new stop. The RouteSync icon will also be present on the screen on the bottom right hand corner to indicate that the file is being received and processed.
- When the file has been downloaded and processing has been completed, a second pop-up will appear. This pop-up will allow the user to accept the route and also to view the details.
- Once this pop-up has been removed from the UI, a spinning icon will be present while the route is being plotted. The UI will be locked for the duration of the spinning icon.
These pop-up messages can be disabled (See the configuration options detailed below). By default, the pop-ups will be shown.
Depending on the size of the RouteSync file and device performance, all pop-ups may not be seen on CoPilot.