location_manager

Updated: April 19, 2023

Make location information available to client applications

Note: You must be root or have the right abilities to run this service.

Syntax:

location_manager

Runs on:

QNX Neutrino

Options:

None.

Description:

The location manager (location_manager) uses PPS objects to make location information available to client applications. It is automatically installed on your development host when you install the QNX Web Browser.

The location manager supports the following types of positioning method:
  • GPS autonomous — Uses the GPS receiver on the local device to retrieve location information. Global Navigation Satellite System (GNSS) modules that offer services such as GPS and GLONASS support this method.
  • Network — Uses the HostIP.info website to determine the current location, based on the client's networked-assigned IP address. The correctness of the result depends on the contents of the HostIP.info database. If the client's IP address isn't in the database, HostIP.info might return an incorrect location.
  • Best — Uses the method (either GPS autonomous or network) that provides the best possible location fix. This method requires a hybrid approach that combines GNSS and network modules.

The following table lists how the various module types support each positioning method:

Positioning method GNSS Network Hybrid
GPS autonomous X * N/A *
Network N/A X * *
Best X X X
X = can be specified in a location request; * = may be returned as part of a location response; N/A = unsupported, may return an error

PPS objects

To interact with client applications, the location manager publishes the following PPS objects:

Using a single positioning method

You can restrict a client application to use only a specific positioning method. To do so, set the provider and fixtype parameters as follows when issuing a location command to the /pps/services/geolocation/control object:

To use only this method: Do this:
GPS autonomous Set provider to gnss and fixType to gps_autonomous.
Network

Set provider to network and fixType to wifi.

Note that the wifi value simply indicates that this method relies on the assigned IP address of the device.

Control object:

The location manager subscribes to the /pps/services/geolocation/control object to listen for commands from client applications. The object allows clients to issue the following command types:
  • location — Provide a location fix to the client.
  • cancel — Stop providing updates to the client.
  • status — Provide the status of the client's current request.
  • reset — Send a reset request to all location provider modules.

A command may not work with all provider types. For instance, the reset command doesn't apply when you set the provider parameter to network.

Note: The /pps/services/geolocation/control object is a PPS server object that provides point-to-point communication between a server and one or more clients. See the Persistent Publish/Subscribe Developer's Guide for more information on server objects.

Command and response format

To issue commands to /pps/services/geolocation/control, clients send messages in this format:

msg::command\nid::ID\ndat::{JSON_DATA}

The ID is a unique identifier; you can set it to any value you wish. The dat attribute, when required, contains parameters associated with the command.

In response, the location manager issues message in this format:

res::command\nid::ID\dat:{JSON_DATA}\nerrCode::error_code\nerr::short_desc\n
errstr::long_desc

where command and ID are the command and ID specified in the client message, JSON_DATA is JSON-encoded response data, and short_desc and long_desc are short and long string descriptions of error_code.

location command

The location command tells the location manager to provide a location fix to the client. It takes the following parameters:

Parameter Type Description
period Number

The periodic delay, in seconds, between updates.

If you specify 0, the location manager provides a location fix only once.

accuracy Number

The desired accuracy of the location fix, in meters.

If you specify 0, the location manager always provides a location fix, even if the fix is of low accuracy.

last_known Boolean

If true, provide the last known position.

The location manager replies with an error if this attribute is set to true and there is no last known position.

provider String
Use the specified type of location provider. One of:
  • gnss — Use a Global Navigation Satellite System (GNSS) module that offers services such as GPS and GLONASS.
  • network — Use the HostIP.info website to determine the current location, based on the client's networked-assigned IP address.
  • hybrid — Use a hybrid approach that combines GNSS and network modules.

If you leave this field blank, the location manager assumes hybrid.

fix_type String
Use the specified type of location fix. One of:
  • gps_autonomous — Use the GPS receiver on the local device.
  • wifi — Use the network method (i.e. HostIP.info). The wifi value simply indicates that this method relies on the assigned IP address of the device.
  • best — Use the best location service available.

If you leave this field blank, the location manager assumes best.

report_sat Boolean If true, report satellite information.
report_nmea Boolean If true, report NMEA sentences to the client application, if they are available.

Reply

The reply to the location command can include the following attributes:

Attribute Type Description
provider String
The source of the location reply. One of:
  • gnss
  • network
  • hybrid
fix_type String
The type of the location reply. One of:
  • gps_autonomous
  • wifi
  • best
latitude Number

The current latitude, in degrees.

The value ranges from -90 to +90, with a minimum of 6 digits of precision (for instance, 37.123456). A positive value indicates the northern hemisphere; a negative value indicates the southern hemisphere.

longitude Number

The current longitude, in degrees.

The value ranges from -180 to +180, with a minimum of 6 digits of precision (for instance, -122.123456). A positive value indicates the eastern hemisphere; a negative value indicates the western hemisphere.

accuracy Number The accuracy of the 2D position, in meters.
altitude Number The altitude, in meters, measured using Mean Sea Level (MSL).
altitudeAccuracy Number The accuracy of the altitude, in meters.
geoidHeight Number

The modeled distance, in meters, of the geoid above the ellipsoid at the location. Here is one way to calculate this distance:

geoid_height = altitude_referenced_to_ellipsoid - altitude_referenced_to_MSL

A positive value indicates that the geoid is above the ellipsoid; a negative value indicates that it is below the ellipsoid.

For all locations, the value should be in the range of -150 to +150 meters.

heading Number

The current heading, in degrees, clockwise from true north (as defined by the velocity vector, not the device orientation).

The GPS receiver may not provide this value if the device is moving below a certain speed.

speed Number The current horizontal speed, in meters per second.
verticalSpeed Number The current vertical speed, in meters per second.
ttff Number The time to first location fix, in seconds
gpsWeek Number The GPS time, measured in weeks since the GPS epoch (0000 UT on 6 January, 1980).
gpsTow Number The GPS time, measured in milliseconds into the current week.
utc Number The number of milliseconds that have elapsed since the Unix epoch (00:00:00 UTC on 1 January 1970). Corrected for leap seconds. 64-bit integer representation required.
hdop Number The horizontal dilution of precision.
pdop Number The positional dilution of precision.
vdop Number The vertical dilution of precision.
satellites Array

An array of observed satellites. See the Satellite array section below for details.

The reply includes this array only if the report_sat parameter is set to true.

NMEA Array

An array of NMEA sentences.

The reply includes this array only if the report_nmea parameter is set to true.

Satellite array

The reply to a location command can include the satellites attribute, which contains an array of observed satellites:
{{sat1}, {sat2}, {sat3}, ...}

Each member of the array contains the following attributes:

Attribute Type Description
type String The type of satellite.
id Number

The pseudo-random noise (PRN) sequence that the satellite transmits to differentiate itself from other satellites.

Here are the ID ranges for the GPS and GLONASS satellite types:
  • GPS satellite — 1-32
  • GLONASS — 65-88
cno Number The carrier-to-noise ratio for the satellite, in dB/Hz.
ephemeris Boolean If true, the receiver has an ephemeris for this satellite.
azimuth Number The azimuth of the satellite, in degrees clockwise from true north.
elevation Number The elevation of the satellite, in degrees from the horizontal plane (i.e. above horizon, no terrain).
tracked Boolean If true, the receiver is tracking this satellite.
used Boolean If true, the receiver is using this satellite to compute the position.
almanac Boolean If true, the receiver has an almanac for this satellite.

cancel command

The cancel command tells the location manager to stop providing updates to the client. It takes no dat parameters.

Reply

The location manager doesn't reply to cancel commands.

status command

The status command tells the location manager to provide the status of the client's current request. It takes no dat parameters.

Reply

The reply to the status command contains the following attributes:

Parameter Type Description
active_request Boolean Indicates whether the client has an active request with the location manager. If true, the reply includes the following fields.
period Number The requested delay, in seconds, between updates.
accuracy Number The requested accuracy, in meters.
response_time Number The requested response time, in seconds.

reset command

The reset command tells the location manager to send a reset request to all of the location provider modules. It takes the following parameter:
Parameter Type Description
reset_type String
Perform the specified reset. One of:
  • almanac
  • cold
  • hot
  • ee_data
  • ephemeris
  • factory
  • warm

Note that some providers may support only a subset of these reset types.

Reply

The location manager doesn't reply to reset commands.

Example location command

Tell the location manager to provide a location fix once every second from a GNSS location provider, to use the best location service available, to report satellite information, and to report NMEA sentences:
msg::location\nid::test\ndat:json:{
    "period": 1, 
    "provider":"gnss", 
    "fix_type":"best", 
    "report_sat":true,
    "report_nmea":true
}	

In response, the location manager issues a reply like the following (for the sake of brevity, some members of the satellites array have been omitted):

@control
res::location
id::test
dat:json: {
            "provider": "gnss",
            "fix_type": "gps_autonomous",
            "latitude": 45.3456098,
            "longitude": -75.8126319,
            "altitude": 60094.5,
            "altitudeAccuracy": 3181.5,
            "geoidHeight": 0,
            "heading": 0,
            "speed": 0,
            "verticalSpeed": 0,
            "ttff": 0,
            "gpsWeek": 1994,
            "gpsTow": 269966000,
            "utc": 1522205950000,
            "hdop": 7.9,
            "pdop": 15,
            "propagated": true,
            "satellites": [
              {
                "type": "GPS",
                "id": 2,
                "cno": 42,
                "ephemeris": true,
                "azimuth": 263,
                "elevation": 48,
                "tracked": true,
                "used": true,
                "almanac": true
              },
              {
                "type": "GPS",
                "id": 3,
                "cno": 19,
                "ephemeris": false,
                "azimuth": 39,
                "elevation": 11,
                "tracked": true,
                "used": false,
                "almanac": true
              },              
            ],
            "NMEA": [
              {
                "name": "GPGSV",
                "sentence": "$GLGSV,3,2,10,79,28,248,26,80,24,318,18,81,58,330,23,
                    82,16,291,19"
              },
              {
                "name": "GPGSV",
                "sentence": "$GLGSV,3,3,10,87,06,091,,88,47,066,"
              }
            ]
          }

Status object:

The location manager populates the /pps/services/geolocation/status object at startup so that applications can monitor its status.

Here is an example of the object:

@status
status:json:{
    "location_manager_location_on":true,
    "location_manager_location_gnss_on":true
}

Attributes

Attribute Type Description
location_manager_location_on
Boolean Indicates whether the location manager is running. Either true (running) or false (not running).
location_manager_location_gnss_on
Boolean Indicates whether GNSS has been enabled. Either true (enabled) or false (not enabled).