RouteSync

Overview

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 CPIK 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.

Detour 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 rejoin the prescribed route. The original RouteSync favors are fully maintained. All road links originally part of RouteSync are still given 100% cost reduction, so it is likely that the route will take the most immediate path back as described, including guidance on smaller local roads and U-turns.

Moderate: CoPilot will try to navigate back to the original route but will take into account the driver’s current position; navigating back to the original route but in most cases using a more reasonable route path. It is less likely to use small local roads or request a U-turn than Strict compliance. The original RouteSync favors are maintained but the original RouteSync road links all receive 40% cost reduction. This likely will pull the route back to the original path, but it will not be as aggressive as Strict in doing so.

Minimal: The original prescribed route is not taken into consideration. The new route planned may still rejoin the original route, but this is because it is the CoPilot default route path and not related to RouteSync. CoPilot will revert back to full link costs and will let the routing algorithm proceed as normal to get to the final destination.

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 CPIK 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:

1. There will be no notification as out of route.
2. The route guidance will not follow any strict route recalculations to return until the beginning of the managed route section.

Route Conflicts

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.)

Safety is the No. 1 priority. CoPilot will attempt to generate the route requested, but it will not ignore road restrictions. Any road that CoPilot deems “closed” to travel based on physical or legal road restrictions will be avoided. In these scenarios, CoPilot will follow the RouteSync prescribed route as closely as it can, but it will leave the route plan to avoid these closures.

If the driver ignores CoPilot’s instructions, and takes a road CoPilot considers unsafe—for example, a road that is height-restricted because of the vehicle’s dimensions—CoPilot warns the driver they are currently on a restricted road. It also stops all audio and visual guidance for the duration of the restricted road.

CoPilot behaves this way in any similar situation whether or not RouteSync is in use.

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 CPIK 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 CPIK libraries, you can pass in a new final destination or simply a blank destination to completely erase.

Exiting CoPilot

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:

1. 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.

2. Multiple loops around a roundabout before taking the 1st exit.

3. 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.

4. 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

• Msg_SendFlex

• Msg_SetFlexCallback

Non-PC*Miler integrations to send RouteSync route:

• Msg_SendManagedRouteJSON

• Msg_ManagedRouteCallback

• MsgSdkManagedRouteCB

Universal API to receive points included within the input but not on the CoPilot route:

• Msg_GetPointsOffRouteSyncRoute

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.

Via Msg_GetRoutingEvent

Route Calculation:

• MSG_IDT_ROUTECALC_START

• MSG_IDT_ROUTECALC_PROGRESS

• MSG_IDT_ROUTECALC_END

• MSG_IDT_ROUTE_CALCFAILED

Truck Restrictions:

• MSG_IDT_ROUTE_RESTRICTEDDEST

• MSG_IDT_ROUTE_RESTRICTEDROAD

• MSG_IDT_RESTRICTED_ROAD

Reaching the destination:

• MSG_IDT_DESTINATION_REACHED

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.

• Msg_SendGenericData
  • MSG_COPILOT_LOCK_CONTROL
  • MSG_COPILOT_UNLOCK_CONTROL

RouteSync APIs for CPIK libraries

The following APIs can be used to send RouteSync routes to CoPilot CPIK libraries deployments. This will allow for the sending of routes as well as call backs and notifications.

PC*Miler Generated RouteSync File

• RouteSync.sendManagedRoute(DAT File)

Non-PC*Miler integrations to send RouteSync route

• RouteSync.sendManagedRouteJSON

Monitoring CoPilot Routing Notifications

RouteListener

• onOutOfRoute
• onRejoinRoute
• onRouteSyncError
• onRouteSyncRouteIntegrated

User.cfg Options for RouteSync

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:

Second Pass

• To allow more granular routes to be generated, CoPilot will execute a second processing of the data.

[RouteSync]
"SecondPass"=true

Audio notification

• To disable the audio announcement. Default=true

[RouteSync]
"RouteSyncSpeechMsgEnabled"=0

RouteSync Control

• 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

RouteSync First Stop

• This config determines whether CoPilot navigates to the closest point on the route from the current GPS location or to the first stop in the RouteSync file. It is enabled by default. When it is enabled (1), the first stop from the RouteSync input file is replaced with the current location. In other words, if the RouteSync file has stops A -> B -> C, stop A is replaced with Current Location, and the stop list in CoPilot is: Current Location -> closest point on the RS route -> stop B -> stop C, once the trip is active.

[User Settings]
"RouteSyncReplaceFirstStop"=1

• To disable the above feature, RouteSyncReplaceFirstStop should be set to 0. When this configuration setting is disabled, the driver is navigated to the first stop in the RouteSync input file, i.e.: Current Location -> stop A -> B -> C

[User Settings]
"RouteSyncReplaceFirstStop"=0

• Alternatively, you can set a distance in miles that determines whether CoPilot navigates to the first stop in the RouteSync file or to the closest point on the route from the current GPS location. If the driver’s current location is within this distance and the first stop, they are 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 is navigated to the first stop on the RouteSync route.

[User Settings]
"RouteSyncOriginMilesDelta"=5

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.

1. 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.
2. 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.
3. 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.
4. 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 above). By default, the pop-ups will be shown.

Note: Depending on the size of the RouteSync file and device performance, all pop-ups may not be seen on CoPilot.