Positioning

In this guide you will learn how to use different techniques to add positioning to your application.

SimpleMap with positioning

First, get an API key token, see the Getting Started guide.

Qt should be installed to continue.

The Maps SDK for Qt should be installed, see the Setup Maps SDK for Qt guide.

Overview

So, let’s add positioning support to the SimpleMap example.

GeneralMagic QML plugin supports a few ways to feed the navigation engine with positions:

1) Use Qt’s PositionSource. PositionSource has plenty of plugins which should support most of the situations out there.

2) Feed the engine with external positions. This should be by far your last choice, and it should be used only if PositionSource can not be used for this job.

Using Qt’s PositionSource

Qt’s PositionSource is by far the easiest way to feed GeneralMagic with positions. As mentioned above, we do recommend you to use this option. There is no need to duplicate the excellent PositionSource documentation; we suggest you read it

here

Following are some examples to walk you through the major plugins:

For Android, iOS there is no need for any special configurations to PositionSource

// QML code
import QtPositioning 5.12
// ...
    PositionSource {
        id: qtPositionSource
        active: true
        Component.onCompleted: ServicesManager.dataSource.setPositionSource(qtPositionSource)
    }
// ...

Yes, that’s all you need to do to feed GeneralMagic with positions!

For (embedded) linux this is a little more tricky. First and foremost it depends on the device itself. If your device is supported by one of the existing plugins (e.g. geoclue, gypsy) then you need first to setup the daemons, then just specify which plugin you’re going to use.

Let’s say your embedded system has setup gypsy daemon; in this case your QML code will look like this:

// QML code
import QtPositioning 5.12
// ...
    PositionSource {
        id: qtPositionSource
        name: "gypsy"
        active: true
        Component.onCompleted: ServicesManager.dataSource.setPositionSource(qtPositionSource)
    }
// ...

Most of the GPS devices support serial NMEA communication; if using gypsy or geoclue is too computation intensive for your device, you can use

serialnmea

plugin instead which is pretty lightweight. In this case your QML code will be slightly longer as we need to also specify the port:

// QML code
import QtPositioning 5.12
// ...
    PositionSource {
        id: qtPositionSource
        name: "serialnmea"
        active: true

        // assuming that your GPS receiver is registered as /dev/ttyUSB0, we need to tell serialnmea plugin about it:
        PluginParameter { name: "serialnmea.serial_port"; value: "ttyUSB0" }
        // alternatively you can set QT_NMEA_SERIAL_PORT env variable to ttyUSB0 and you can drop the PluginParameter line

        Component.onCompleted: ServicesManager.dataSource.setPositionSource(qtPositionSource)
    }
// ...

Custom crafted positions

If there is no way to use PositionSource then you can still feed the GeneralMagic QML plugin with positions. Here is a mock QML example which should give you an idea how to push the positions to the engine:

// QML code
// ...
// Custom crafted positions
function feedEngine(externalPos)
{
    let pos = ServicesManager.createPosition();
    // mandatory fields
    pos.timeStamp = externalPos.time_stamp; // do not use new Date() !
    pos.latitude = externalPos.latitude;
    pos.longitude = externalPos.longitude;
    pos.horizontalAccuracy = externalPos.horizontal_accuracy;
    pos.speed = externalPos.speed;
    pos.course = externalPos.course;
    pos.courseAccuracy = externalPos.course_accuracy;

    // optional fields. All these fields are filled with default values,
    // so if you don't have valid values, do no set them
    if (externalPos.has_altitude)
        pos.altitude = externalPos.altitude;
    if (externalPos.has_vertical_accuracy)
        pos.verticalAccuracy = externalPos.vertical_accuracy;
    if (externalPos.has_speed_accuracy)
        pos.speedAccuracy = externalPos.speed_accuracy;

    // finally push the position to the engine
    ServicesManager.dataSource.pushPosition(pos);
}

// Let's say you have custom position source named MyCustomPositionSource
// which will notify us via PositionUpdated signal when it has a new position
MyCustomPositionSource {
    onPositionUpdated: feedEngine(position)
}

Be aware that failing to set all the mandatory fields with sane data, will break the GeneralMagic behavior. E.g. setting timeStamp to something like new Date() most of the time will not work properly as it doesn’t come from the GPS device and it will be slightly shifted. Optional fields are also very important and they should be omitted only if that data is not available at all.

QML Examples

Maps SDK for Qt Examples can be downloaded or cloned with Git