Skip to main content

gnss-session.readposition(infoCallback, mode)

Acquire positioning information from the GNSS sub-system

Availability

Device (from impOS™ 43)
Only available on imps with cellular modems

Parameters

Name Type Description
infoCallback Function An information delivery callback
mode Integer Optional latitude and longitude display format. Default: 0

Returns

Nothing

Description

This method retrieves device location data from the GNSS sub-system, which must be enabled before this call can be made.

An exception is raised if gnss-session.readposition() is called while another GNSS-related callback is pending. An existing callback can only be cancelled by deleting the parent gnss-session object.

The value passed into the optional parameter mode is an integer which determines the format of the location data taken from the GPGGA sentence and returned by the method:

Mode Longitude Format Latitude Format
0 ddmm.mmmm N/S ddmm.mmmm E/W
1 ddmm.mmmmmm N/S ddmm.mmmmmm E/W
2 (-)dd.ddddd (-)dd.ddddd

Latitude degree values lie in the range 00-89 (modes 0 and 1) or -89.99999-89.99999 (mode 2).

Longitude degree values lie in the range 00-179 (modes 0 and 1) or -179.99999-179.99999 (mode 2).

Minute values in the range 00.0000-59.9999 (mode 0) or 00.000000-59.999999 (mode 1).

The default is mode 0.

The location data is returned in a table which is passed to the supplied infoCallback function. The table contains at least two keys: status and quectel. The value of status will be zero if no error occurred, or an error code (see gnss-session for details).

The value of the key quectel is a table containing zero or more of the following keys:

Key Description
utc Current UTC time in the format hhmmss.sss
latitude The latitude reading, formatted as above
longitude The longitude reading, formatted as above
hdop Horizontal precision in the range 0.5—99.9
altitude Altitude in meters
fix The GNSS positioning mode:
2 — 2D
3 — 3D
cog Course Over Ground based on true north. Format: ddd.mmnm, where:
ddd = 000-359 degrees
mmm = 00-59 minutes
spkm Speed over ground in km/h. Format: xxxx.x
spkn Speed over ground in knots. Format: xxxx.x
date UTC date of fix in the format ddmmyy
nsat Number of satellites in range 0-12

Example Code

The following example shows the basic steps required to get a device’s location fix by GNSS on a cellular imp006. It uses a sequence of API calls to open a GNSS session then to use that session first to enable GNSS and then to determine the device’s location. The code makes recursive calls to enableGNSS() until the modem is ready to read the device’s location, then recursive calls to getLocation() until a fix is achieved or an error occurred.