Positioning

API Reference
Positioning Control Reference

---

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.

IPC interfaces binding

All the functions of this API are provided by the positioningService application service.

Here's a code sample binding to Positioning services:

bindings:
{
   clientExe.clientComponent.le_pos -> positioningService.le_pos
}

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_GetTime() function gets the time of last updated position:

• Hours into the day [range 0..23].
• Minutes into the hour [range 0..59].
• Seconds into the minute [range 0..59].
• Milliseconds into the second [range 0..999].

The le_pos_GetDate() function gets the date of last updated position:

• Year A.D. [e.g. 2014].
• Month into the year [range 1...12].
• Days into the month [range 1...31].

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_Get2DLocation()
• le_pos_sample_GetDate()
• le_pos_sample_GetTime()
• le_pos_sample_GetAltitude()
• le_pos_sample_GetHorizontalSpeed()
• le_pos_sample_GetVerticalSpeed()
• le_pos_sample_GetHeading()
• le_pos_sample_GetDirection()

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.

---

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