GPS

Msg_SendGPSPositionRequest

Request current position information from CoPilot. Including the current lat/long, vehicle speed and heading.

Syntax (Prototyped in alkmsg.h)

long Msg_SendGPSPositionRequest(void);

Notes

In order to retrieve the current position, you must have previously set a callback for the Msg_ID_GPSPosition message. This is done as follows:

private void OnGenericInformation(uint pData, uint bytes)
(
  uint lMsgID = (uint)Msg.Msg_CreateGenericInformation(Msg_IDT_LANEASSIST);
  Msg.Msg_CreateGenericInformationAddDetail(lMsgID, -1, 0, 0, 0, null, null);
  Msg.Msg_SendGenericInformation(lMsgID, -1, -1);
  Msg_ParserDelete(lMsgID);
)

Return Value

• ≤ 0 Failed

• 0 Successful

Msg_GPSPositionGet

Decode and retrieve the current position information from CoPilot from a Msg_ID_GPSPosition message. Including the current lat/long, vehicle speed and heading.

Syntax (Prototyped in alkmsg.h)

long Msg_GPSPositionGet(void *pMsg,
                        double &dLat,
                        double &dLon,
                        double &dHeading,
                        double &dSpeed,
                        long &UTCDate,
                        long &UTCTime,
                        long &lAltitude,
                        double &dPDOP,
                        short &sFixMode,
                        short &sSatelliteCount);

Parameters

Return Value

• ≤ 0 Failed

• 0 Successful

Note

CoPilot passes raw GPS feed received from the GPS receiver to the client application. No data massaging is done to account for the occasional aberrant reading from the antenna. So for example, if client application is displaying the speed of the vehicle, the client application may get an abnormally high speed reported from the receiver (ex: 200 mph) due to GPS signal distortions.

When no new GPS position is available or we do not have a GPS fix, CoPilot will send out last known location. CoPilot saves the last known location every minute and during exit. When the last known location is sent, the sFixMode value is 0, 1 indicating that CoPilot have a 2D GPS fix but not acquired 3D fix. Also dHeading will be 0. When CoPilot has acquired 3D GPS fix, the sFixMode value is 2.

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 0.122805W & 51.518220N so it should be pass as a -122805 longitude & 51518220 latitude.

Msg_SendNMEA

Sends an NMEA-formatted message to the CoPilot application. Used to provide GPS information into CoPilot via the client application. The CoPilot application will treat this message as if it was received from a locally-attached GPS device. All messages must end with the ASCII characters 13, 10 (0x0D, 0x0A).

Syntax (Prototyped in alkmsg.h)

long Msg_SendNMEA(const char *pszNMEA,
                  long lDestID = CONN_ID_NONE,
                  long lSrcID = CONN_ID_NONE);

Parameters

Return Value

• ≤ 0 Failed

• 0 Successful

Note

If client application switches between actual GPS receiver & Msg_SendNMEA, then the client application must use Msg_SendGenericData (Msg_IDT_REOPENGPSPORT) once it stops sending the NMEA message to inform CoPilot of the change. If the client application fails to send Msg_IDT_REOPENGPSPORT then CoPilot will always waiting for SDK to send NMEA message and never pickup the already configured GPS.

Please note that the Route Preview uses the same function call as Send_NMEA, therefore any time you provide an NMEA feed, Route Preview will not function correctly, showing only your NMEA feed.

Using external GPS receiver by CoPilot in Android

If Location Based Service or GPS is Off in Android, CoPilot will prompt the message “Would you like to enable the GPS?” message every time you start the CoPilot. If customer is either using external GPS receiver or Msg_SendNMEA message, customer can disable this message by using following configuration setting in user.cfg or product.cfg

GPS
"ShowGPSDisabledWarning" = 0

NMEA Support for CoPilot

CoPilot works with NMEA-compliant GPS receivers that meet two requirements:

1. GPS receiver must output the following NMEA messages: GGA, GSA, GSV, and RMC.
   Note The NMEA standard includes seven (7) output messages. CoPilot only requires the four (4) listed above

2. Optimal routing functionality is achieved when these messages are output every second.

NMEA strings required by CoPilot: GPRMC, GPGSA and GPGSV to lock a 3D position. CoPilot requires RMC each second. This holds the coordinate information. CoPilot also needs GPGSA messages, or GPGGA messages sent every second. The GSA is preferred. GGA message is used if CoPilot has not received a GSA in 5 seconds.

Please ensure client application send one NMEA string at a time and do not bundle the messages together as CoPilot is not able to read the a bundled string.

The GSA message includes a field indicating whether the device is receiving a “credible” 2D or 3D fix. If CoPilot does not receive this message, it makes the assumption that the GPS fix is from an inadequate number of satellites and is not a good fix. Therefore the coordinates cannot be trusted.

CoPilot must have a 3D fix for location updating and route calculation. We do this due to the inaccuracy of any 2D fix, which could be many metres away and may provide an inaccurate route. It takes a minimum of 4 satellite positions to provide a 3D fix although 6-8 satellites are preferable.

CoPilot will read the UTC time from both the RMC and GGA NMEA message strings.

Also remember GPS is affected by many external factors, such as buildings and trees, as the device needs clear line of sight to the satellites. On the first ever run of a GPS with no position history stored can require additional time.

If sending NMEA via an SDK API call, the client application should cancel sending NMEA messages to CoPilot when the application is shutting down, as this may cause issues.

Please find below a sample of the NMEA strings for a UK example:

$GPRMC,150845.000,A,5135.1428,N,00020.4216,W,4.41,302.43,080407,,,A*73
$GPGSA,A,3,13,04,25,02,20,16,,,,,,,2.3,1.5,1.8*38
$GPRMC,150906.000,A,5135.1297,N,00020.4130,W,5.59,245.10,080407,,,A*7C
$GPGSA,A,3,13,25,02,27,20,16,,,,,,,2.2,1.3,1.8*3E
$GPRMC,150909.000,A,5135.1291,N,00020.4240,W,6.87,270.56,080407,,,A*75
$GPGSA,A,3,13,25,02,27,20,16,,,,,,,2.2,1.3,1.8*3E
$GPGSV,3,1,11,13,78,065,16,04,58,222,17,02,44,294,15,25,41,063,22*71
$GPGSV,3,2,11,27,37,164,17,10,12,288,,08,12,179,,20,09,109,23*7A
$GPRMC,151200.000,A,5135.1247,N,00020.3884,W,9.17,167.99,080407,,,A*78
$GPGSA,A,3,04,13,23,25,02,27,20,08,16,10,,,1.4,0.8,1.1*34
$GPRMC,151203.000,A,5135.1151,N,00020.3852,W,13.95,167.85,080407,,,A*48
$GPGSA,A,3,04,13,23,25,02,27,20,08,16,10,,,1.4,0.8,1.1*34
$GPRMC,151206.000,A,5135.1013,N,00020.3807,W,18.62,170.57,080407,,,A*40
$GPGSA,A,3,04,13,23,25,02,27,20,08,16,10,,,1.4,0.8,1.1*34
$GPRMC,151209.000,A,5135.0870,N,00020.3764,W,13.01,167.85,080407,,,A*4E
$GPGSA,A,3,04,13,23,25,02,27,20,08,16,10,,,1.4,0.8,1.1*34
$GPGSV,3,1,11,13,76,063,32,04,57,219,39,02,45,292,32,23,42,063,34*74
$GPGSV,3,2,11,25,40,062,30,27,38,163,39,10,14,289,25,08,13,179,31*7B
$GPRMC,151215.000,A,5135.0805,N,00020.3672,W,9.74,82.29,080407,,,A*42
$GPGSA,A,3,04,13,23,25,02,27,20,08,16,10,,,1.4,0.8,1.1*34
$GPRMC,151218.000,A,5135.0827,N,00020.3478,W,16.92,78.47,080407,,,A*7C
$GPGSA,A,3,04,13,23,25,02,27,20,08,16,10,,,1.4,0.8,1.1*34
$GPRMC,151221.000,A,5135.0860,N,00020.3270,W,11.46,77.99,080407,,,A*79
$GPGSA,A,3,04,13,23,25,02,27,20,08,16,10,,,1.4,0.8,1.1*34
$GPRMC,151224.000,A,5135.0874,N,00020.3154,W,8.98,79.54,080407,,,A*48
$GPGSA,A,3,04,13,23,25,02,27,20,08,16,10,,,1.4,0.8,1.1*34
$GPGSV,3,1,11,13,76,063,37,04,57,219,26,02,45,292,31,23,42,063,35*7D
$GPGSV,3,2,11,25,40,062,34,27,38,163,34,10,14,289,21,08,13,179,22*74
$GPRMC,151227.000,A,5135.0890,N,00020.2991,W,14.75,83.08,080407,,,A*73
$GPGSA,A,3,04,13,23,25,02,27,20,08,16,10,,,1.4,0.8,1.1*34
$GPRMC,151230.000,A,5135.0918,N,00020.2747,W,20.47,75.80,080407,,,A*7E
$GPGSA,A,3,04,13,23,25,02,27,20,08,16,10,,,1.4,0.8,1.1*34
$GPRMC,151233.000,A,5135.0954,N,00020.2493,W,14.33,82.66,080407,,,A*7B
$GPGSA,A,3,04,13,23,25,02,27,20,08,16,10,,,1.4,0.8,1.1*34