Skip to main content

RouteSync

Contents

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 SinceMinimum Operating System
CoPilot 9.2.0Windows 10

Syntax (Prototyped in alkmsg.h)

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

Parameters

ParameterDescription
pDataAny Flex Message being sent to CoPilot. (Currently received Routesync Flex Object from PC MILER)
lByteCountNumber of bytes in pData
fnNotifStatusCBCallback 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);
ParameterDescription
pTokenNot in use
lByteCountNot in use
destIDNot in use
srcIDNot in use
pStateText 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 SinceMinimum Operating System
CoPilot 9.2.0Windows 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

ParameterDescription
pIDFlex 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.
fnNotifSDKDeliverCBCallback function.

Callback Function Description (fnNotifSDKDeliverCB)

typedef long (*NotifStatusCB) (const char* bytes,
   unsigned long numbytes);
ParameterDescription
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 SinceMinimum Operating System
CoPilot 9.6.0Windows 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 ParameterDescriptionRequired
ComplianceThis 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
OorDistanceThis 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
LegsAt least one leg is needed for each managed route. This should be passed as two sets of Coordinates.Yes
CoordsAt 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
TripThe trip detailsYes
ProfileThis 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
nameProfile Name, this should be passed if the Profile group is included.No
vehicleType0:Auto, 2:RV, 3:Truck, 6:Motorcycle, 7:Bicycle, 8:Walking. This should be passed if the Profile group is included.No
routingType0:Quickest, 1:Shortest, 2:Avoid Major Roads. This should be passed if the Profile group is included.No
tollRoadType0:Avoid, 1:Use If Necessary, 2:No Restriction. This should be passed if the Profile group is included.No
maxHeightValue 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
maxWidthHundredths 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
totalLengthHundredths 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
totalWeightPounds. 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
totalWeightPerAxlePounds. 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
hazmatType0: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 attributeNo
displayRestrictions0: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
nationalNetworkFor 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
fiftyThreeFootTrailerFor 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
overrideRestrictionsSet 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
bordersOpenFor North American customers if they wish to set the borders open parameter in the routing profile this should be setNo
propaneFor North American customers who have a routing profile that needs to have the propane restriction set this parameter can be usedNo
ferryClosedTo set the ferry routing attributeNo
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 drivingNo
LowEmissionZonesOpen
Available in CoPilot 10.14 and Higher
Sets a routing preference for Low Emission Zones. 0: Avoid, 1: Allow, 2: Warn when drivingNo
StopsMust always have one more stop than legsYes
LocationDetails about the stop.Yes
AddressThe 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
StreetAddressFirst line of the address of the StopNo
CityCity of the StopNo
StateState of the stopNo
ZipZip or Postal Code for the stopNo
CountyCounty of the stopNo
CountryCountry code for the stopNo
CoordsThe stop can be passed using the Coords or Address. If Address has not been provided this is mandatory.Yes, if no Address supplied
LatMandatory if using Coords for geocoding the stopYes, if using Coords
LonMandatory if using Coords for geocoding the stopYes, if using Coords
WaypointDefault is false. If you would like to set the stop as a Waypoint rather than a stop this should be set to True.No
NameStop name – default is blankNo

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 SinceMinimum Operating System
CoPilot 9.2.0, Deprecated CoPilot 10.4.0Windows 10, Android 4.1

Parameter

ParameterDescription
LatlongSeries 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 “ | ”. For multiple destinations, start and destination need to be followed by “1”.
eOORComplianceRoute compliance option that indicates how strongly should CoPilot navigate to the original prescribed route. 0 – Strict Compliance, 1 – Moderate Compliance, 2 – No Compliance
dOORDistOut 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

ValueDescription
-3Indicates the latlong list is empty.
-2Indicates that there are too many latlongs provided and the operation can not continue.
-1Error
Greater than zeroSuccessful 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 SinceMinimum Operating System
CoPilot 9.2.0Windows 10, Android 4.1

Syntax (Prototyped in alkmsg.h)

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

Parameter

ParameterDescription
fnProcessMsgType call back function of the following type.
typedeflong (MsgSdkManagedRouteCB) (char cName, int iResponse); Convention
Calling conventionManaged 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 SinceMinimum Operating System
CoPilot 9.2.0Windows 10, Android 4.1

Syntax (Prototyped in alkmsg.h)

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

Parameter

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

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 SinceMinimum Operating System
CoPilot 9.2.0Windows 10, Android 4.1

Syntax (Prototyped in alkmsg.h)

long MsgGetPointsOffRouteSyncRoute(void _pBytes, unsigned long bytesLen, char strPayload, long lPayload);

Parameter

ParameterDescription
pBytesThe message buffer passed by the system to the user-specified callback function, set by Msg_UpdateOptions().
bytesLenBuffer length
strPayloadString payload of the list of coordinated that are outside of the generated route
lPayloadLength of the strPayload

Return Value

  • Less than 0 = Failed
  • Greater than 0 = Successful
Last updated November 23, 2021.
Contents