Acquire positioning information from the GNSS sub-system
Device
Only available on imps with cellular modems
| Name | Type | Description |
|---|---|---|
| infoCallback | Function |
An information delivery callback
|
| mode | Integer |
Optional latitude and longitude display format. Default: 0
|
Nothing
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 degreesmmm = 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 |
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 calls to getLocation() to request a fix.