Skip to content

RouteSync

RouteSync is a feature which aids route compliance and improves in-vehicle consistency from the back office to the mobile workforce devices. Routes can be planned on back office systems and by passing location information via API to CoPilot this route will be sent to CoPilot.

Msg_SendFlex

This API is used to send flex message (flex object) to CoPilot. Currently only used for sending RouteSync Flex object to CoPilot (received from PC*MILER). This API should be used to handle, parse, and call appropriate callbacks under this framework which will be done by CoPilot and alksdk.dll

The messaging framework will provide the message updates by calling Notification Status Callback. (E.g Received\@CoPilot, Received\@Client, Accepted\@CoPilot etc)

Supported Since Minimum Operating System
CoPilot 9.2.0 Windows 10

Syntax (Prototyped in alkmsg.h)

long Msg_SendFlex (const char *pdata,
   unsigned long lByteCount,
   NotifStatusCB fnNotifStatusCB);

Parameters

Parameter Description
pData Any Flex Message being sent to CoPilot. (Currently received Routesync Flex Object from PC MILER)
lByteCount Number of bytes in pData
fnNotifStatusCB Callback function which is being called to provide status of the flex message. Presently only RouteSync Object from PC MILER is supported.

Callback Function Description (fnNotifStatusCB)

typedef long (*NotifStatusCB) (const char* pToken,
   unsigned long ulTokenBytes,
   long srcID,
   long destID,
   const char* pState);
Parameter Description
pToken Not in use
lByteCount Not in use
destID Not in use
srcID Not in use
pState Text based notification of the message (E.g Received\@CoPilot, Received\@Client, Accepted\@CoPilot etc)

Return Value

  • -1 - (Signifies that there was an error).
  • 0 - or any positive value (Signifies that value is set successfully).

Msg_SetFlexCallback

This API is used to register for callback for specific type “flex message type”. Once registered for specific flex message (defined using the pID), flex messaging framework will call registered callback once it receives the particular type of flex message from CoPilot.

Supported Since Minimum Operating System
CoPilot 9.2.0 Windows 10

Notes

In order to get more details about implementation as well RouteSyncEvent, please refer to the SDK Sample Application. Implementation of .NET can be found in C# sample application. Implementation of Java can be found in SDK Application in Android.

Syntax (Prototyped in alkmsg.h)

long Msg_SetFlexCallback (const char *pID,
   NotifSDKDeliverCB
   fnNotifSDKDeliverCB);

Parameters

Parameter Description
pID Flex Message Type. Supported now: “TSendRouteSyncEvent”: Marshals the stream of bytes into RouteSyncEvent object that contains all of the relevant information about the event.  This is sent whenever a vehicle deviates from or rejoins a RouteSync route. “TSendRouteSyncSummary”: Marshals the stream of bytes into RouteSyncEvent objects that contains all of the relevant information about the event.  Summary is generally being sent by CoPilot when user reached to destination. Both the above callbacks have to be set for RouteSync. This might be increased to support for other messages in future.
fnNotifSDKDeliverCB Callback function.

Callback Function Description (fnNotifSDKDeliverCB)

typedef long (*NotifStatusCB) (const char* bytes,
   unsigned long numbytes);
Parameter Description
bytes: Buffer pointer which contains different type of data based on flex message callback
numbytes: Number of bytes in buffer

Return Value

  • -1 - (Signifies that there was an error).
  • 0 - or any positive value (Signifies that value is set successfully).

Msg_SendManagedRouteJSON

This API is used to send a RouteSync message in JSON format from the client application to CoPilot.

Supported Since Minimum Operating System
CoPilot 9.6.0 Windows 10, Android 4.1

Syntax (Prototyped in alkmsg.h)

long Msg_SendManagedRouteJSON(const char* pJson);

Parameter

pJson: Complete contents of a JSON message describing a CoPilot managed route. See Note 1 for details on this format.

Return Value

-1 = Error parsing JSON Greater than zero = Successful in sending the request to CoPilot.

Related API’s

Msg_ManagedRouteCallback - Used to set the callback and receive notification about successful processing of the message by CoPilot. Msg_SetFlexCallback MsgSdkManagedRouteCB

Note

The following is a description of the JSON format expected by the API including optional/required fields.

JSON Format

{
    "Compliance": 0,
    "OorDistance": 0.2,
    "Legs": [
      {
        "Coords": [
          -74730013,   //Coords for roads you'd like the route to follow from Stop A -> Stop B
          40297252
]
      },
      {
        "Coords": [
          -74660179,   //Coords for roads you'd like the route to follow from Stop B -> Stop C
          40348429,
          -74660635,
          40349433]
      }
    ],
 "Trip": {
      "Name": "Test name",
      "Profile": {
            "name": "",
            "vehicleType": 4,
            "routingType": 3,
            "tollRoadType": 2,
            "maxHeight": 12900,
            "maxWidth": 9600,
            "totalLength": 48000,
            "totalWeight": 3300,
            "totalWeightPerAxle": 2300,
            "hazmatType": 0,
            "displayRestrictions": 2,
            "nationalNetwork": false,
            "fiftyThreeFootTrailer": false,
            "overrideRestrictions": true,
            "bordersOpen": true,
            "CongestionZonesOpen": 0,
            "LowEmissionZonesOpen": 0,
            "propane": false,
            "ferryClosed": false,
            "tollAvoid": false,
            "tollClosed": false,
            "truckDimensions": 0,
            "wrongSideofStreetCost": 1000,
            "autoSetStopDirection": 1
        },
      "Stops": [
        {
          "Location": {
            "Address": {
              "StreetAddress": "",
              "City": "Lawrence Township",
              "State": "NJ",
              "Zip": "08648",
              "County": "Mercer",
              "Country": ""
            },
            "Coords": {
              "Lat": "40.297263",
              "Lon": "-74.730034"
            }
          },
          "Waypoint": false,
          "Name": "Stop A"
        },
        {
          "Location": {
            "Coords": {
              "Lat": "40.348727",
              "Lon": "-74.659049"
            }
          },
          "Waypoint": false,
          "Name": "Stop B"
        },
        {
          "Location": {
            "Address": {
              "StreetAddress": "",
              "City": "New York",
              "State": "NY",
              "Zip": "10001",
              "County": "New York",
              "Country": ""
            }
          },
          "Waypoint": false,
      "Name": "Stop C"
        }
      ]
    }
  }
JSON Parameter Description Required
Compliance This value will dictate how CoPilot will handle re-routing. That is, how strictly CoPilot should try to return to the original (sent) route in the event that the driver is out-of-route. There are three possible values: 0 – Strict Compliance; 1 – Moderate Compliance; 2 – Minimal Compliance. Yes
OorDistance This value will determine how far away from the planned route the CoPilot-equipped vehicle must be to generate an out-of-route (OOR) alert. The default value is 0.2 miles. Yes
Legs At least one leg is needed for each managed route. This should be passed as two sets of Coordinates. Yes
Coords At least 2 coords per leg are required. These are latitude and longitude points between stops on the trip that create the route you want the driver to follow. We recommend at least one latitude and longitude location for every road you want the route to follow, and an additional latitude and longitude on each side of every turning junction. These should be passed as long integers and encoded as millionths of a degree. Yes
Trip The trip details Yes
Profile This passes the Vehicle Routing Profile that is used for the managed route. Note: While optional, this parameter is highly recommended. Otherwise, CoPilot will use the current routing profile on the device to generate the route. No, but recommended
name Profile Name, this should be passed if the Profile group is included. No
vehicleType 0:Auto, 2:RV, 3:Truck, 6:Motorcycle, 7:Bicycle, 8:Walking. This should be passed if the Profile group is included. No
routingType 0:Quickest, 1:Shortest, 2:Avoid Major Roads. This should be passed if the Profile group is included. No
tollRoadType 0:Avoid, 1:Use If Necessary, 2:No Restriction. This should be passed if the Profile group is included. No
maxHeight Value sent in hundredths of inches. If sending in the routing profile and it is a truck vehicle type with a vehicle height you would like to specify, include this parameter. No
maxWidth Hundredths of inches. If sending in the routing profile and it is a truck vehicle type with a vehicle width you would like to specify, include this parameter. No
totalLength Hundredths of inches. If sending in the routing profile and it is a truck vehicle type with a vehicle length you would like to specify, include this parameter. No
totalWeight Pounds. If sending in the routing profile and it is a truck vehicle type with a vehicle weight you would like to specify, include this parameter. No
totalWeightPerAxle Pounds. If sending in the routing profile and it is a truck vehicle type with a vehicle weight per axle group you would like to specify, include this parameter. No
hazmatType 0:None, 1:General, 2:Explosive, 3:Inhalant, 4:Radioactive, 5:Caustic, 6:Flammable, 7:Harmful to water. If sending a Truck routing profile and you wish to specify any Hazmat category that may be applicable include this attribute No
displayRestrictions 0:Off, 1:On, 2:Based on profile. Within the truck routing profile that you are sending to CoPilot if you wish to include the setting to show restrictions on the map, include this parameter. No
nationalNetwork For North American customers, if sending a truck profile and you wish to apply the nationalNetwork routing profile setting this should be set with this parameter. No
fiftyThreeFootTrailer For North American customers sending a truck profile and wish to set the Fifty Three Foot Trailer setting within the routing profile, this parameter should be used. No
overrideRestrictions Set to true to to generate routes that waive truck restrictions pertaining to specific sizes and weights, but that continue to avoid truck-prohibited and truck discouraged roads. No
bordersOpen For North American customers if they wish to set the borders open parameter in the routing profile this should be set No
propane For North American customers who have a routing profile that needs to have the propane restriction set this parameter can be used No
ferryClosed To set the ferry routing attribute No
wrongSideofStreetCost
Available in CoPilot 10.14 and Higher
For School Bus profiles, set to 1000. This value favors approaching a stop on the same side of the road that you are driving on. It helps prevent a situation in which a student has to cross the road to get on the bus. No
autoSetStopDirection
Available in CoPilot 10.14 and Higher
For School Bus profiles, set to 1. This prevents a vehicle from making a U-turn at a stop. No
CongestionZonesOpen
Available in CoPilot 10.14 and Higher
Sets a routing preference for Congestion Zones 0: Avoid, 1: Allow, 2: Warn when driving No
LowEmissionZonesOpen
Available in CoPilot 10.14 and Higher
Sets a routing preference for Low Emission Zones. 0: Avoid, 1: Allow, 2: Warn when driving No
Stops Must always have one more stop than legs Yes
Location Details about the stop. Yes
Address The stop can be passed using the Address or the Coords. One of these options must be provided as part of the Stops Location section. Yes, if no Coords supplied
StreetAddress First line of the address of the Stop No
City City of the Stop No
State State of the stop No
Zip Zip or Postal Code for the stop No
County County of the stop No
Country Country code for the stop No
Coords The stop can be passed using the Coords or Address. If Address has not been provided this is mandatory. Yes, if no Address supplied
Lat Mandatory if using Coords for geocoding the stop Yes, if using Coords
Lon Mandatory if using Coords for geocoding the stop Yes, if using Coords
Waypoint Default is false. If you would like to set the stop as a Waypoint rather than a stop this should be set to True. No
Name Stop name – default is blank No

Msg_SendManagedRoute

This API is used to send the RouteSync message from a series of lat/long to CoPilot from the client application. When the lat/long positions are sent to CoPilot a compliance and out of route alert parameter should be included. The compliance parameter will indicate how strongly CoPilot should route the driver back to the RouteSync route if they leave the route. If the route is left, a warning callback can be triggered via the out of route distance information.

Please note this API is deprecated within CoPilot Version 10. Msg_SendManagedRouteJSON is recommended to be used in place of this API. Syntax (Prototyped in alkmsg.h) long Msg_SendManagedRoute(char* latLongs, int eOORCompliance, double dOORDist);

Supported Since Minimum Operating System
CoPilot 9.2.0, Deprecated CoPilot 10.4.0 Windows 10, Android 4.1

Parameter

Parameter Description
Latlong Series of lat/long (please note Lat/Long value to multiplied by 1,000,000). Start and Destination to be followed by “1”(Example 42636605,-76178562,1). Individual lat/longs to be separated by the “
eOORCompliance Route compliance option that indicates how strongly should CoPilot navigate to the original prescribed route. 0 – Strict Compliance, 1 – Moderate Compliance, 2 – No Compliance
dOORDist Out of route alert distance option that indicates how far can CoPilot deviate from the original prescribed route before the OOR alert is issued. Default is 0.2 miles.

Return Value

Value Description
-3 Indicates the latlong list is empty.
-2 Indicates that there are too many latlongs provided and the operation can not continue.
-1 Error
Greater than zero Successful in sending the request to CoPilot.

Related APIs Msg_ManagedRouteCallback Msg_SetFlexCallback MsgSdkManagedRouteCB

Note

This API can be use in coordination with MSG_IDT_ROUTE_LATLONLIST. MSG_IDT_ROUTE_LATLONLIST retrieve lat/long for the given route which can be pass to Msg_SendManagedRoute to verify the that Msg_SendManagedRoute follows exactly same route for test environment.

Tip

Can handle multiple start/stop pair. Stops are written as follows – Example - “42636605,-76178562,1”. The 1 identifies it as a stop. For further details about eOORCompliance and CoPilot behavior, please refer to the CoPilot Feature Guide.


Msg_ManagedRouteCallback

This API is used to set callback to receive notifications when sending a managed route request (as a series of lat/long or JSON) using Msg_SendManagedRouteJSON.

Supported Since Minimum Operating System
CoPilot 9.2.0 Windows 10, Android 4.1

Syntax (Prototyped in alkmsg.h)

long Msg_ManagedRouteCallback(void* fnProcessMsg, callingConvention convention = convention_default);

Parameter

Parameter Description
fnProcessMsg Type call back function of the following type.
typedef long (MsgSdkManagedRouteCB) (char cName, int iResponse); Convention
Calling convention Managed Apps should use convention_stdcall

Return Value 1

Related API’s Msg_SendManagedRouteJSON MsgSdkManagedRouteCB Msg_SetFlexCallback

Enum

enum callingConvention {
  convention_default,
  convention_cdecl,
  convention_stdcall
};

MsgSdkManagedRouteCB

Function definition of the callback function when setting a callback using Msg_ManagedRouteCallback.

Supported Since Minimum Operating System
CoPilot 9.2.0 Windows 10, Android 4.1

Syntax (Prototyped in alkmsg.h)

typedef long (*MsgSdkManagedRouteCB) (char* cName, int iResponse);

Parameter

Parameter Description
cName Flex message name cStr String requested to be played
iResponse -3,-2,-1, 1
iResponse Description
-1 Parsing Error Or Not Enough Points
-2 Pipe or comma is not placed correctly in input.
-3 Input was parsed but CoPilot couldn’t not generate the managed route.
1 Success

Return Value - 1


Msg_GetPointsOffRouteSyncRoute

Provides details of the lat/long coordinates that are included within the RouteSync input file but are not on the route generated by CoPilot. These details are provided through the subscription of MSG_ID_RouteSyncPointsOff.

Supported Since Minimum Operating System
CoPilot 9.2.0 Windows 10, Android 4.1

Syntax (Prototyped in alkmsg.h)

long Msg_GetPointsOffRouteSyncRoute(void pBytes, unsigned long bytesLen, char strPayload, long lPayload);

Parameter

Parameter Description
pBytes The message buffer passed by the system to the user-specified callback function, set by Msg_UpdateOptions().
bytesLen Buffer length
strPayload String payload of the list of coordinated that are outside of the generated route
lPayload Length of the strPayload

Return Value

  • Less than 0 = Failed
  • Greater than 0 = Successful

Last update: June 11, 2020