Click here for the positioning API reference documentation.

Fix On Demand
Navigation
Positioning Xtra injection
Positioning configuration tree

This API provides access to the device's physical position and movement information.

Note: Enabling and disabling the positioning system is a privileged operation available only through the Positioning Control API.

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 Xtra injection

With le_pos_LoadXtra() , you can load a xtra.bin file from the filesystem. You have to download the file before loading it.

with le_pos_GetXtraValidity(), you will retrieve the date between the xtra is still validate.

Example:

#define XTRA_PATH     "/tmp/xtra.bin"
le_clk_Time_t start,stop;
char startTime[100] = {0};
char StopTime[100] = {0};
// download file into XTRA_PATH
DownloadXtraFile(XTRA_PATH);
if ( le_pos_LoadXtra(XTRA_PATH) != LE_OK )
{
   LE_WARN("Could not load '%s'",XTRA_PATH);
}
if ( le_pos_GetXtraValidity(&start,&stop) != LE_OK )
{
   LE_WARN("Could get the validity");
}
if ( le_clk_ConvertToUTCString(start,
                               LE_CLK_STRING_FORMAT_DATE_TIME,
                               startTime,
                               sizeof(startTime),
                               NULL) != LE_OK )
{
    LE_INFO("Could not convert start time");
}
if ( le_clk_ConvertToUTCString(stop,
                               LE_CLK_STRING_FORMAT_DATE_TIME,
                               StopTime,
                               sizeof(StopTime),
                               NULL) != LE_OK )
{
    LE_INFO("Could not convert stop time");
}
LE_INFO("Validity Start time  %s",startTime);
LE_INFO("Validity Stop time %s",StopTime);

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.

Copyright (C) Sierra Wireless, Inc. 2014. Use of this work is subject to license.