Click here for the API reference documentation.

This file contains the the prototype definitions of the high level Positioning APIs.

Fix On Demand
Navigation
Positioning configuration tree

You need to know the location and the current movement information to precisely track machine position.

This module provides an API to retrieve the position's information.

Fix On Demand

The le_pos_Get2DLocation() function gets the last updated latitude, longitude and the horizontal accuracy values:

latitude is in degrees, positive North.
longitude is in degrees, positive East.
horizontal accuracy is in metres.

The latitude and longitude are given in degrees with 6 decimal places like:

Latitude +48858300 = 48.858300 degrees North
Longitude +2294400 = 2.294400 degrees East

The le_pos_Get3DLocation() function gets the last updated latitude, longitude, altitude and their associated accuracy values.

altitude is in metres, above Mean Sea Level, with 3 decimal places (3047 = 3.047 metres).
horizontal and vertical accuracies are in metres.

The le_pos_GetMotion() function gets the last updated horizontal and vertical speed values and the associated accuracy values:

horizontal speed is in m/sec.
vertical speed is in m/sec, positive up.

The le_pos_GetHeading() function gets the last updated heading value in degrees (where 0 is True North) and its associated accuracy value. Heading is the direction that the vehicle/person is facing.

The le_pos_GetDirection() function gets the last updated direction value in degrees (where 0 is True North) and its associated accuracy value. Direction of movement is the direction that the vehicle/person is actually moving.

Navigation

To be notified when the device is in motion, you must register an handler function to get the new position's data. The le_pos_AddMovementHandler() API registers that handler. The horizontal and vertical change is measured in metres so only movement over the threshhold will trigger notification (0 means we don't care about changes).

The handler will give a reference to the position sample object that has triggered the notification. You can then access parameters using accessor functions, and release the object when done with it.

The accessor functions are:

le_pos_sample_Release() releases the object.

You can uninstall the handler function by calling the le_pos_RemoveMovementHandler() API.

Note:: The le_pos_RemoveMovementHandler() API does not delete the Position Object. The caller has to delete it by calling the le_pos_sample_Release() function.

In the following code sample, the function InstallGeoFenceHandler() installs an handler function that triggers an alarm if the device leaves a designated location.

 #define GEOFENCE_CENTRE_LATITUDE            +48070380  // Latitude 48.070380 degrees North
 #define GEOFENCE_CENTRE_LONGITUDE           -11310000  // Longitude 11.310000 degrees West
 #define MAX_METRES_FROM_GEOFENCE_CENTRE     150

 static le_event_HandlerRef_t GeoFenceHandlerRef;

 void InstallGeoFenceHandler()
 {
     // I set my home latitude and longitude where my device is located
     SetHomeLocation(HOME_LATITUDE, HOME_LONGITUDE);

     MyPositionUpdateHandlerRef = le_pos_AddMovementHandler(50, // 50 metres
                                                            0,  // I don't care about changes of altitude.
                                                            MyPositionUpdateHandler,
                                                            NULL);
 }


 static void MyPositionUpdateHandler
 (
     le_pos_SampleRef_t     positionSampleRef,
     void*                  contextPtr
 )
 {
     int32_t metresFromCentre;

     int32_t accuracyMetres;
     int32_t latitude;
     int32_t longitude;

     le_pos_sample_Get2DLocation(positionSampleRef, &latitude, &longitude, &accuracyMetres);

     metresFromCentre = le_pos_ComputeDistance(GEOFENCE_CENTRE_LATITUDE, GEOFENCE_CENTRE_LONGITUDE
                                               latitude, longitude);

     if (metresFromCentre > MAX_METRES_FROM_GEOFENCE_CENTRE)
     {
         // Check it doesn't just look like we are outside the fence because of bad accuracy.
         if (  (accuracyMetres > metresFromCentre) ||
               ((metresFromCentre - accuracyMetres) < MAX_METRES_FROM_GEOFENCE_CENTRE)  )
         {
             // Could be outside the fence, but we also could be inside the fence.
         }
         else
         {
             // Definitely outside the fence!
             RaiseAlarm(positionSampleRef);
         }
     }

     le_pos_sample_Release(positionSampleRef);
 }

Positioning configuration tree

The configuration database path for Positioning is:

   /
       positioning/
           acquisitionRate<int> == 5

'acquisitionRate' is the fix acquisition rate in seconds.

Note:: If there is no configuration for 'acquisitionRate', it will be automatically set to 5 seconds.