Skip to content

Optimization

ALK_SendRouteHeader

This function is used to pass in the route header information. It is the first function that needs to be called before passing in the stops. It defines driver start time, start location and end location.

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

CoPilot SDK

long ALK_SendRouteHeader (short sStartTime,
   int lStartStopLat,
   int lStartStopLon,
   int lEndStopLat,
   int lEndStopLon);

Parameters

Parameter Description
sStartTime Start Time of the Trip (Minutes starting from midnight E.g 07.00AM can be represented 60* 7 = 420, 14.30pm can be represented using 60*14 + 30 = 870)
lStartStopLat Latitude of the starting stop from where route will be started, typically it will be a depot. It will express as a long value in millionths of a degree.
lStartStopLon Longitude of the starting stop from where route will be started, typically it will be a depot. It will express as a long value in millionths of a degree.
lEndStopLat Latitude of the ending stop where route will be end, typically it will be a depot. It will express as a long value in millionths of a degree.
lEndStopLon Longitude of the ending stop where route will be end, typically it will be a depot. It will express as a long value in millionths of a degree.

Return Value

  • ≤0 - Failed
  • Greater than 0 - Successful

Notes

All Latitude and Longitude values are sent as long integers. These values are encoded as millionths of a degree. North and East are positive values, South and West are negative values. For example, the Trimble MAPS London office is located at 51.51822N & 0.122805W so it should be pass as a 51518220 latitude & -122805 longitude.

The SDK optimization sample application uses a 24hr format for the input time. The SDK app demonstrates how to convert the time to minutes from midnight. This is because reading the input file is simpler in a 24hr format.


ALK_SendRouteStop

This function will pass the destination address details; including open and close window time and the onsite wait time. This function needs to be called for each destination.

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

CoPilot SDK

long ALK_SendRouteStop (short sStopNo,
   char *pStreetAddress,
   char *pOptionalAddress1,
   char *pOptionalAddress2,
   char *pOptionalAddress3,
   char *pCity,
   char *pPostalCode,
   char *pCountry,
   int lLat,
   int lLon,

short sStartTimeConstraint,
   short sEndTimeConstraint,
   short sWaitTime);

Parameters

Parameter Description
sStopNo Stop number provided by client application. It must be a unique of all passing stops.
pStreetAddress Street number and street name of the stop
pOptionalAddress1 Optional Address details of the stop.
pOptionalAddress2 Optional Address details of the stop.
pOptionalAddress3 Optional Address details of the stop.
pCity City/Area for stop
pPostalCode Postal code for stop
pCountry Country for the stop
lLat Latitude of the stop. It will express as a long value in millionths of a degree.
lLon Longitude of the stop. It will express as a long value in millionths of a degree.
sStartTimeConstraint Start time constraint for the stop (Minutes starting from midnight).
sEndTimeConstraint End time constraint for the stop (Minutes starting from midnight).
sWaitTime Wait time (Seconds). The wait time is the time the driver will be at the stop completing the required task before continuing driving.

Return Value

  • Less than or equal to 0 - Failed
  • Greater than 0 - Successful

Notes

All Latitude and Longitude values are sent as long integers. These values are encoded as millionths of a degree. North and East are positive values, South and West are negative values. For example, the Trimble MAPS London office is located at 51.51822N & 0.122805W so it should be pass as a 51518220 latitude & -122805 longitude.

If the input fileaddress details includes Latitude and Longitude values, CoPilot will only use these for the geocode location for optimizationdetails exclusively, regardless of the addressadditional information passed at the same time. This helps to speed up the optimization process without the need for multiple geocoding. This is different to our API for adding addresses into CoPilot via Msg_TripAddStopWithHouseNum.

Within the input file Stop number 1 should be passed as the first stop and an increment of 1 for each subsequent stop should be passed to ensure consistent output results are received.

If you wish to define the starting or end stops within an input file and exclude them from the optimization Static Stops enable this. To utilise static stops at the beginning or end of the route the stop should be given the stop number 2001 and incrementing my 1 for each subsequent static stop. Static stops can only be included at the beginning and/or end of an input file. Time windows will not be considered in these cases. For further information please refer to the CoPilot ReadMe Feature Guide.

Time Constraints

Although CoPilot software does not specifically have any restrictions on the length of Time Constraint window, it is advisable to allow a minimum of 1 hour between the sStartTimeConstraint and sEndTimeConstraint. This allows CoPilot sufficient time to optimize the route efficiently. If you require a time window less than 1 hour please discuss it with us prior to implementation, by emailing CoPilotPro@ALK.Com.

If the Time Constraint Window is not feasible to be met, i.e. the driver does not leave the depot before the End Time Constraint CoPilot will optimize the stop as soon as possible after the time window has ended.


ALK_SendRouteStopWithBlockWindowTime

This function will pass the destination address details; including open and close window time and the onsite wait time (same as ALK_SendRouteStop), in addition, the blocking window open and close time. A blocking time means, do not reach this destination between these two times. For example a shop is open between 9am to 5 but closes 12pm to 1pm for lunch.

For each destination, any one of the 3 SendRouteStop functions needs to be called

ALK_SendRouteStop
      ALK_SendRouteStopWithBlockWindowTime
      ALK_SendRouteStopWithSecondWindowTime
Supported Since Minimum Operating System
CoPilot 9.2.1 Windows 10, Android 4.1

CoPilot SDK

long ALK_SendRouteStopWithBlockWindowTime (short sStopNo,
               const char *pStreetAddress,
               const char *pCity,
               const char *pPostalCode,
               const char *pCountry,
               long lLat,
               long lLon,
               short sOpenWindowStartTime,
               short sOpenWindowEndTime,
               short sWaitTime,
               short sBlockWindowStartTime,
               short sBlockWindowEndTime);

Parameters

Parameter Description
sStopNo Stop number provided by client application. It must be a unique of all passing stops.
pStreetAddress
pCity
pPostalCode
pCountry
lLat Latitude of the stop. It will express as a long value in millionths of a degree.
lLon Longitude of the stop. It will express as a long value in millionths of a degree.
sOpenWindowStartTime Start time constraint for the stop (Minutes starting from midnight).
sOpenWindowEndTime End time constraint for the stop (Minutes starting from midnight).
sWaitTime Wait time (Seconds). The wait time is the time the driver will be at the stop completing the required task before continuing driving.
sBlockWindowStartTime Blocking window start time (Minutes starting from midnight).
sBlockWindowEndTime Blocking window end time (Minutes starting from midnight).

Return Value

  • Less than or equal to 0 - Failed
  • Greater than 0 - Successful

Notes

All Latitude and Longitude values are sent as long integers. These values are encoded as millionths of a degree. North and East are positive values, South and West are negative values. For example, the Trimble MAPS London office is located at 51.51822N & 0.122805W so it should be pass as a 51518220 latitude & -122805 longitude.

If the input fileaddress details includes Latitude and Longitude values, CoPilot will only use these for the geocode location for optimizationdetails exclusively, regardless of the addressadditional information passed at the same time. This helps to speed up the optimization process without the need for multiple geocoding. This is different to our API for adding addresses into CoPilot via Msg_TripAddStopWithHouseNum.

Time Constraints, although CoPilot software does not specifically have any restrictions on the length of Time Constraint window, it is advisable to allow a minimum of 1 hour between the sOpenWindowStartTime and sOpenWindowEndTime. This allows CoPilot sufficient time to optimize the route efficiently. If you require a time window less than 1 hour please discuss it with us prior to implementation, by emailing copilotpro@alk.com.

If the Time Constraint Window is not feasible to be met, i.e. the driver does not leave the depot before the End Time Constraint CoPilot will optimize the stop as soon as possible after the time window has ended.

If there is no blocking window time, sBlockWindowStartTime and sBlockWindowEndTime can be set as 0.

Within the input file Stop number 1 should be passed as the first stop and an increment of 1 for each subsequent stop should be passed to ensure consistent output results are received.


ALK_SendRouteStopWithSecondWindowTime

This function will pass the destination address details; including open and close window time and the onsite wait time (same as ALK_SendRouteStop), in addition, a second window open and close time.

A second time window is when you provide two positive destination reached time. For example a shop is open between 9am to 12pm and 1pm to 5pm.

For each destination, one of the 3 SendRouteStop functions needs to be called

ALK_SendRouteStop ALK_SendRouteStopWithBlockWindowTime ALK_SendRouteStopWithSecondWindowTime

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

CoPilot SDK

long ALK_ SendRouteStopWithSecondWindowTime (short sStopNo,
  const char *pStreetAddress,
  const char *pCity,
  const char *pPostalCode,
  const char *pCountry,
  long lLat,
  long lLon,
  short sOpenWindowStartTime,
  short sOpenWindowEndTime,
  short sWaitTime,
  short sSecondWindowStartTime,
  short sSecondWindowEndTime);

Parameters

Parameter Description
sStopNo Stop number provided by client application. It must be a unique of all passing stops.
pStreetAddress Street number and street name of the stop
pCity City/Area for stop
pPostalCode Postal code for stop
pCountry Country for the stop
lLat Latitude of the stop. It will express as a long value in millionths of a degree.
lLon Longitude of the stop. It will express as a long value in millionths of a degree.
sOpenWindowStartTime Start time constraint for the stop (Minutes starting from midnight).
sOpenWindowEndTime End time constraint for the stop (Minutes starting from midnight).
sWaitTime Wait time (Seconds). The wait time is the time the driver will be at the stop completing the required task before continuing driving.
sSecondWindowStartTime Second open window start time (Minutes starting from midnight).
sSecondWindowEndTime Second open window end time (Minutes starting from midnight).

Return Value

  • Less than or equal to 0 = Failed
  • Greater than 0 Successful

Notes

All Latitude and Longitude values are sent as long integers. These values are encoded as millionths of a degree. North and East are positive values, South and West are negative values. For example, the Trimble MAPS London office is located at 51.51822N & 0.122805W so it should be pass as a 51518220 latitude & -122805 longitude.

If the input fileaddress details includes Latitude and Longitude values, CoPilot will only use these for the geocode location for optimizationdetails exclusively, regardless of the addressadditional information passed at the same time. This helps to speed up the optimization process without the need for multiple geocoding. This is different to our API for adding addresses into CoPilot via Msg_TripAddStopWithHouseNum.

Time Constraints

Although CoPilot software does not specifically have any restrictions on the length of Time Constraint window, it is advisable to allow a minimum of 1 hour between the sOpenWindowStartTime and sOpenWindowEndTime. This allows CoPilot sufficient time to optimize the route efficiently. If you require a time window less than 1 hour please discuss it with us prior to implementation, by emailing copilotpro@alk.com

If the Time Constraint Window is not feasible to be met, i.e. the driver does not leave the depot before the End Time Constraint CoPilot will optimize the stop as soon as possible after the time window has ended.

If there is no second open window time, sSecondWindowStartTime and sSecondWindowEndTime can be set as 0.

Within the input file Stop number 1 should be passed as the first stop and an increment of 1 for each subsequent stop should be passed to ensure consistent output results are received.


ALK_SendRouteStopWithBlockWindowTimeWithClusterID

Please use this API only in consultation with us on the implementation as it may have detrimental impact to the optimized output.

This function will pass the destination address details; including open and close window time and the onsite wait time (same as ALK_SendRouteStop), in addition, the blocking window open and close time. A blocking time means, do not reach this destination between these two times. For example a shop is open between 9am to 5 but closes 12pm to 1pm for lunch.

This API also includes the Unique Cluster ID. This can be used to override the CoPilot clustering logic or merge with the CoPilot clustering logic as needed to improve the optimization in line with business process

The Unique cluster ID will coerce the algorithm to cluster destinations together based on these IDs. It never uses only the unique cluster ID by itself and clusters can still break apart during sequencing. However, stops with the same unique cluster ID are more likely to be sequenced together in the end result.

When using the Unique Cluster ID it is possible to set 3 different strictness values using the below Configuration settings added to user.cfg

[Optimization]
"UniqueClusterStrictness"=0

This is the default setting for CoPilot, 0 will disable the use of Unique Cluster ID’s using CoPilot clustering logic alone

"UniqueClusterStrictness"=1

This will cluster with CoPilot clustering logic and also try to cluster stops using the Unique Cluster ID. It will also use will use the CoPilot logic to break up clusters when they cause an increase in time window failures.

"UniqueClusterStrictness"=2

Using this setting will place all the emphasis on the Cluster ID, CoPilot cluster logic is disabled, this may lead to an increase of missed Time Windows. It is not advised to use this setting unless you are confident that your clusters are already considering time windows, or if you have minimal time windowed stops

The use of unique clusters is likely to significantly impact the optimized route provided by CoPilot. Without the use of unique clusters CoPilot will implement its own cluster logic and as a result it is not always needed.

For each destination, any one of the 3 SendRouteStop functions needs to be called

  • ALK_SendRouteStop
  • ALK_SendRouteStopWithBlockWindowTime
  • ALK_SendRouteStopWithSecondWindowTime
Supported Since Minimum Operating System
CoPilot 10.9.0 Windows 10, Android 4.1

Syntax (Prototyped in alkmsg.h)

long ALK_SendRouteStopWithBlockWindowTimewithClusterID
  (short sStopNo,
const char *pStreetAddress,
const char *pCity,
const char *pPostalCode,
const char *pCountry,
int lLat,
int lLon,
short sOpenWindowStartTime,
short sOpenWindowEndTime,
short sWaitTime,
short sBlockWindowStartTime,
short sBlockWindowEndTime,
const char *pClusterID);

Parameters

Parameter Description
sStopNo Stop number provided by client application. It must be a unique of all passing stops.
pStreetAddress House number and street name for the stop
pCity City for the stop
pPostalCode Postal code for the stop
pCountry Country for the stop
lLat Latitude of the stop. It will express as a long value in millionths of a degree.
lLon Longitude of the stop. It will express as a long value in millionths of a degree.
sOpenWindowStartTime Start time constraint for the stop (Minutes starting from midnight).
sOpenWindowEndTime End time constraint for the stop (Minutes starting from midnight).
sWaitTime Wait time (Seconds). The wait time is the time the driver will be at the stop completing the required task before continuing driving.
sBlockWindowStartTime Blocking window start time (Minutes starting from midnight).
sBlockWindowEndTime Blocking window end time (Minutes starting from midnight).
pClusterID This is the unique cluster ID, multiple stops can include the same unique cluster ID. All stops with the same cluster ID will be considered for delivery together in the same cluster, but these may be broken up during the processing if needed to meet time windows

Notes

All Latitude and Longitude values are sent as long integers. These values are encoded as millionths of a degree. North and East are positive values, South and West are negative values. For example, the Trimble MAPS London office is located at 51.51822N & 0.122805W so it should be pass as a 51518220 latitude & -122805 longitude.

If the input file address details includes Latitude and Longitude values, CoPilot will only use these for the geocode location for optimization details exclusively, regardless of the address additional information passed at the same time. This helps to speed up the optimization process without the need for multiple geocoding. This is different to our API for adding addresses into CoPilot via Msg_TripAddStopWithHouseNumprovided.

Time Constraints

Although CoPilot software does not specifically have any restrictions on the length of Time Constraint window, it is advisable to allow a minimum of 1 hour between the sOpenWindowStartTime and sOpenWindowEndTime. This allows CoPilot sufficient time to optimize the route efficiently.

If the Time Constraint Window is not feasible to be met, i.e. the driver does not leave the depot before the End Time Constraint CoPilot will optimize the stop as soon as possible after the time window has ended.

If there is no blocking window time, sBlockWindowStartTime and sBlockWindowEndTime can be set as 0. Within the input file Stop number 1 should be passed as the first stop and an increment of 1 for each subsequent stop should be passed to ensure consistent output results are received.

Return Value

  • Less than or equal to 0 = Failed
  • Greater than 0 = Successful

ALK_SendRouteStopWithSecondWindowTimeWithClusterID

!!! Warning: Please use this API only in consultation with us on the implementation as it may have detrimental impact to the optimized output.

This function will pass the destination address details; including open and close window time and the onsite wait time (same as ALK_SendRouteStop), in addition, a second time window open and close time. A second time window is when you provide two positive destination reached times. For example a shop is open between 9am to 12pm and 1pm to 5pm.

This API also includes the Unique Cluster ID. This can be used to override the CoPilot clustering logic or merge with the CoPilot clustering logic as needed to improve the optimization in line with business process.

The Unique cluster ID will coerce the algorithm to cluster destinations together based on these IDs. It never uses only the unique cluster ID by itself and clusters can still break apart during sequencing. However, stops with the same unique cluster ID are more likely to be sequenced together in the end result.

When using the Unique Cluster ID it is possible to set 3 different strictness values using the below Configuration settings added to user.cfg

[Optimization]
"UniqueClusterStrictness"=0

This is the default setting for CoPilot, 0 will disable the use of Unique Cluster ID’s using CoPilot clustering logic alone

"UniqueClusterStrictness"=1

This will cluster with CoPilot clustering logic and also try to cluster stops using the Unique Cluster ID. It will also use will use the CoPilot logic to break up clusters when they cause an increase in time window failures.

"UniqueClusterStrictness"=2

Using this setting will place all the emphasis on the Cluster ID, CoPilot cluster logic is disabled, this may lead to an increase of missed Time Windows. It is not advised to use this setting unless you are confident that your clusters are already considering time windows, or if you have minimal time windowed stops

The use of unique clusters is likely to significantly impact the optimized route provided by CoPilot. Without the use of unique clusters CoPilot will implement its own cluster logic and as a result it is not always needed.

For each destination, any one of the 3 SendRouteStop functions needs to be called:

  • ALK_SendRouteStop
  • ALK_SendRouteStopWithBlockWindowTime
  • ALK_SendRouteStopWithSecondWindowTime
Supported Since Minimum Operating System
CoPilot 10.9.0 Windows 10, Android 4.1

Syntax (Prototyped in alkmsg.h)

long ALK_SendRouteStopWithSecondWindowTimewithClusterID
  (short sStopNo,
const char *pStreetAddress,
const char *pCity,
const char *pPostalCode,
const char *pCountry,
int lLat,
int lLon,
short sOpenWindowStartTime,
short sOpenWindowEndTime,
short sWaitTime,
short sSecondWindowStartTime,
short sSecondWindowEndTime,
const char *pClusterID);

Parameters

Parameter Description
sStopNo Stop number provided by client application. It must be a unique of all passing stops.
pStreetAddress House number and street name for the stop
pCity City for the stop
pPostalCode Postal code for the stop
pCountry Country for the stop
lLat Latitude of the stop. It will express as a long value in millionths of a degree.
lLon Longitude of the stop. It will express as a long value in millionths of a degree.
sOpenWindowStartTime Start time constraint for the stop (Minutes starting from midnight).
sOpenWindowEndTime End time constraint for the stop (Minutes starting from midnight).
sWaitTime Wait time (Seconds). The wait time is the time the driver will be at the stop completing the required task before continuing driving.
sBlockWindowStartTime Blocking window start time (Minutes starting from midnight).
sBlockWindowEndTime Blocking window end time (Minutes starting from midnight).
pClusterID This is the unique cluster ID, multiple stops can include the same unique cluster ID. All stops with the same cluster ID will be considered for delivery together in the same cluster, but these may be broken up during the processing if needed to meet time windows

Notes

All Latitude and Longitude values are sent as long integers. These values are encoded as millionths of a degree. North and East are positive values, South and West are negative values. For example, the Trimble MAPS London office is located at 51.51822N & 0.122805W so it should be pass as a 51518220 latitude & -122805 longitude.

If the input file address details includes Latitude and Longitude values, CoPilot will only use these for the geocode location for optimization details exclusively, regardless of the address additional information passed at the same time. This helps to speed up the optimization process without the need for multiple geocoding. This is different to our API for adding addresses into CoPilot via Msg_TripAddStopWithHouseNumprovided.

Time Constraints

Although CoPilot software does not specifically have any restrictions on the length of Time Constraint window, it is advisable to allow a minimum of 1 hour between the sOpenWindowStartTime and sOpenWindowEndTime. This allows CoPilot sufficient time to optimize the route efficiently. If the Time Constraint Window is not feasible to be met, i.e. the driver does not leave the depot before the End Time Constraint CoPilot will optimize the stop as soon as possible after the time window has ended. If there is no second time window, sSecondWindowStartTime and sSecondWindowEndTime can be set as 0. Within the input file Stop number 1 should be passed as the first stop and an increment of 1 for each subsequent stop should be passed to ensure consistent output results are received.

Return Value

  • Less than or equal to 0 = Failed
  • Greater than 0 = Successful

ALK_StartETACalculation

After passing route header and destination details, call this function to start the Optimization and/or ETA calculation process.

This event will also return notifications and error values:

  • Notifications: Geocoding started, geocoding completed, Calculation started, Calculation Completed, Calculation Timed Out, Calculation user cancelled, Calculation is running,

  • Errors: Depot non geocodable, geocoding stop errors, destination geocoded significant distance from other stops, destination will not be reached before midnight, complete route cannot be completed within 24 hours.

  • Geocode Results: This will return the latitude and longitude locations for every destination passed to CoPilot.

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

CoPilot SDK

long ALK_StartETACalculation     (void *pEventCallback,
  long lTimeOut,
  bool bOptimize, callingConvention convention = convention_default,
  long lDestID =CONN_ID_NONE,
  long lSrcID = CONN_ID_NONE);

Parameters

Parameter Description
pOptCallback Callback function which will provide the status, results of the ETA calculation. Please read following description.
lTimeOut Timeout in seconds. Will timeout if the route calculation has not completed within the required period
bOptimize true : by passing true CoPilot will optimize the stop sequence and provide ETA based on the new sequence
false : by passing false, CoPilot will provide a complete ETA only based on given stop sequence and wait times
convention Convention for callback function
lDestID Destination ID received in the callback function established for handling connection event change messages (this callback function is the first parameter passed to Msg_Startup call). Omit or set to CONN_ID_NONE when sending CoPilot control commands to same local machine.

Return Value

  • ≤0 Failed
  • Greater than 0 = Successful
enum callingConvention {
   convention_default,
   convention_cdecl,
   convention_stdcall
};

void ETACallback (ETAEvent sEvent,
       int info1,
       int info2,
       int info3,
       int info4 );

//If bOptimize = false
typedef enum
{

HEADER_DETAILS,                   //info1 : ETA for the end stop (typically depot)
                                  //info2 : Total distance from start depot to end depot by using given stop sequence in miles
                                  //info3 : Unused
                                  //info4 : Unused

STOP_DETAILS,                     //info1 : Given stop sequence number
                                  //info2 : ETA based on given stop sequence
                                  //info3 : Unused
                                  //info4 : Distance in miles from previous stop. It will express as a long value in hundredth of actual value. To get actual value, divide the value by 100. If distance between stop is 2.7 miles, it will return as a 270.

ETA_CALCULATION_STARTED,          //Ignore all the parameter
ETA_CALCULATION_COMPLETED,        //Ignore all the parameter
ETA_CALCULATION_TIMEOUT,          //Ignore all the parameter
ETA_CALCULATION_CANCEL,           //Ignore all the parameter
ETA_CALCULATION_RUNNING,          //Ignore all the parameter
ETA_DEPOT_NONGEOCODABLE           //Ignore all the parameter
ETA_STOP_ERRORS                   //info1 : Stop error type
                                  //info2 : Additional info based on error code
ETA_EVENT_NOTIFICATION            //info1 : Notification Type
                                  //info2 : Notification Related Info
                                  //info3 : Notification Related Info
                                  //info4 : Notification Related Info
STOP_GEOCODE_RESULT               //info1 : Given stop sequence number
                                  //info2 : Latitude of stop
                                  //info3 : Longitude of stop
                                  //info4 : Currently not supported
} ETAEvent;

//If bOptimize = true
typedef enum
{
HEADER_DETAILS,                    //info1 : Optimized ETA for the end stop (typically depot)
                                   //info2 : Total distance from start Depot to end depot by using optimized route in miles
                                   //info3 : Unused
                                   //info4 : Unused

STOP_DETAILS,                      //info1 : Given stop sequence number
                                   //info2 : ETA based on optimized stop sequence
                                   //info3 : Optimized stop sequence number
                                   //info4 : Distance in miles from previous stop. It will express as a long value in hundredth of actual value. To get actual value, divide the value by 100. If distance between stop is 2.7 miles, it will return as a 270.

ETA_CALCULATION_STARTED,           //Ignore all the parameter
ETA_CALCULATION_COMPLETED,         //Ignore all the parameter
ETA_CALCULATION_TIMEOUT,           //Ignore all the parameter
ETA_CALCULATION_CANCEL,            //Ignore all the parameter
ETA_CALCULATION_RUNNING,           //Ignore all the parameter
ETA_DEPOT_NONGEOCODABLE,           //Ignore all the parameter
ETA_STOP_ERRORS                    //info1 : Stop error type
                                   //info2 : Additional info based on error code

ETA_EVENT_NOTIFICATION             //info1 : Notification Type
                                   //info2 : Notification Related Info
                                   //info3 : Notification Related Info
                                   //info4 : Notification Related Info

STOP_GEOCODE_RESULT                //info1 : Given stop sequence number
                                   //info2 : Latitude of stop
                                   //info3 : Longitude of stop
                                   //info4 : Currently not supported

} ETAEvent;

sEvent : Event depending upon the progress of optimization

sEvent Value Description
ETA_CALCULATION_STARTED Started to calculate ETA.
ETA_CALCULATION_COMPLETED ETA calculation completed.
ETA_CALCULATION_TIMEOUT Timeout before ETA calculation completed.
ETA_CALCULATION_CANCEL User has canceled ETA calculation before it is
completed through Msg_StopETACalculation.
ETA_CALCULATION_RUNNING Optimization or ETA calculation is already running in CoPilot and you can not initiate second instance of Optimization or ETAcalculation.
ETA_DEPOT_NONGEOCODABLE Start depot or end depot are not geocodable. It means either it is wrong latitude/longitude or in wrong format.
ETA_STOP_ERRORS It will provide different type of error event i.e stop not geocoded, delivery will take more than 24 hours, delivery will cross midnight etc. Following section contain different error type supported. Part of info1.
#define STOP_ERROR_MAXDISTANCE       0x02
#define STOP_ERROR_DELIVERY_24HOURS  0x03
#define STOP_ERROR_DELIVERY_MIDNIGHT 0x04
#define STOP_ERROR_TIME_WINDOW       0x05
#define STOP_ERROR_WAIT_TIME         0x06

STOP_ERROR_MAXDISTANCE: Will provide notification when stop is more than 100 miles away from route, this stop will be removed from the optimization list. info2 contain original stop number.

Max Distance Error configuration.

By default CoPilot sets the max distance as 100 miles, this is measured as a matrix of all stops to identify any that are potentially in correct locations. This means that if a destination is over 100 miles away from all other stops it will be removed from the optimization. To change the default value add the following section to the:

Program Files / CoPilot / user.cfg file

[Optimization]

“MaxAirTravelMile”=100

STOP_ERROR_DELIVERY_24HOURS: Will provide notification when delivery time will take more than 24 hours.

STOP_ERROR_DELIVERY_MIDNIGHT: Will provide notification when delivery time for given stop pass through midnight. info2 contain original stop number. info 2 contains negative value for returning depot.

STOP_ERROR_TIME_WINDOW This provides notification when the destination close time is earlier than its own start time or the depot start time.

STOP_ERROR_WAIT_TIME This provides notification when wait time for a regular stop is more than 30 minutes or wait time for a break stop is more than 2 hours.

STOP_ERROR_BREAK_INSERT This provides notification a stop was marked as a break stop but could not be inserted into the end sequence. Common reasons for this error include setting a break time outside of the driver's working hours or setting a final break time after the final stop has been completed.

ETA_EVENT_NOTIFICATION: It will provide different type of notification from the optimization engine e.g. Geocode started, Geocode Finished etc. Following section contain different notification type supported.

#define GEOCODE_STARTED 0x01 #define GEOCODE_FINISHED 0x02

GEOCODE_STARTED: Will provide notification when optimization engine start the geocoding of the stops.

GEOCODE_FINISHED: Will provide notification when optimization engine finish the geocoding of the stops.

STOP_GEOCODE_RESULT: It will provide Geocoded latitude and longitude of the stops. Optimization engine will provide this information during the geocoding of the stops. While passing the stop, if already contains the latitude/longitude, optimization engine will not provide this information.


ALK_StopETACalculation

This call will stop the ETA calculation process at an appropriate time.

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

CoPilot SDK

  long ALK_StopETACalculation (long lDestID =CONN_ID_NONE,
  long lSrcID = CONN_ID_NONE);

Parameters

Parameter Description
lDestID Destination ID received in the callback function established for handling connection event change messages (this callback function is the first parameter passed to Msg_Startup call). Omit or set to CONN_ID_NONE when sending CoPilot control commands to same local machine.
lSrcID Unique ID of the sender of the message. Omit or set to CONN_ID_NONE when sending CoPilot control commands to same local machine.

Return Value

  • Less than or equal to 0 = Failed
  • Greater than 0 = Successful

Last update: August 24, 2020