Turn the GNSS sub-system on
Device
Only available on imps with cellular modems
| Name | Type | Description |
|---|---|---|
| gnssMode | Integer |
The GNSS working mode
|
| fixMaxTime | Integer |
The maximum positioning time in seconds
|
| fixMaxDist | Integer |
The positioning accuracy threshold in meters
|
| fixCount | Integer |
The number of position determination attempts
|
| fixRate | Integer |
The interval between the first and second time positioning in seconds
|
Table — see below
This method activates and configures the GNSS sub-system. The five optional parameters take integer values in fixed ranges as follows:
| Parameter | Value Range | Description |
|---|---|---|
| gnssMode | 1-4 | The GNSS working mode: 1 — standalone (default) 2 — MS-based 3 — MS-assisted 4 — speed-optimal |
| fixMaxTime | 1-255 | The maximum positioning time, ie. the response time of the GNSS receiver while measuring the GNSS pseudo range, and the upper time limit of GNSS satellite searching. It also includes the time for demodulating the ephemeris data and calculating the position. Default: 30 |
| fixMaxDist | 1-1000 | The positioning accuracy threshold in meters. Default: 50 |
| fixCount | 0-1000 | The number of position determination attempts. The value 0 represents continuous positioning. Default: 0 |
| fixRate | 1-65535 | The interval between the first and second time positioning in seconds. Default: 1 |
The returned table contains the key status. Its value will be zero if no error occurred, or an error code (see gnss-session for details).
GNSS session operations are highly asynchronous and, once triggered, modem operations proceed independently of impOS’ Squirrel virtual machine state. This is most noticeable if your application restarts, either intentionally by pushing updated code, or because it was restarted by impOS after it raised an exception. In such cases, when the device is not power-cycled, the state of the modem and the application’s assumptions about modem state may become misaligned. Your code should therefore always check GNSS API responses — returns from the calls, and status values passed to callbacks — to determine modem state before proceeding, and use gnss-session.getstate(), as shown in the code below.
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 getLocation() to get a fix.
| // Hold a reference to the GNSS Session object | |
| gnssSession <- null; | |
| // Store device location | |
| location <- { "lat": 0, "lon": 0 }; | |
| function isGnssEnabled() { | |
| // Is GNSS ready to use? | |
| if (gnssSession == null) return false; | |
| try { | |
| local resp = gnssSession.getstate(); | |
| return (resp.status == 1); | |
| } catch (err) { | |
| return false; | |
| } | |
| } | |
| function enableGNSS() { | |
| // Is GNSS ready? | |
| if (!isGnssEnabled()) { | |
| // Check the modem has a GNSS session in place | |
| if (gnssSession == null) { | |
| // Initiate a session | |
| try { | |
| gnssSession = hardware.gnss.open(function(result) { | |
| server.log("[DEBUG] GNSS Session is " + (result.ready == 0 ? "not ready" : "ready")); | |
| if (result.ready == 1) { | |
| // We're good to enable GNSS operations | |
| enableGNSS(); | |
| } | |
| }); | |
| } catch (error) { | |
| // Back off and try again | |
| imp.wakeup(1, enableGNSS); | |
| } | |
| return; | |
| } | |
| // We have a GNSS session, so enable GNSS operations | |
| local resp = gnssSession.enable(); | |
| if (resp.status != 0) { | |
| // Error enabling GNSS | |
| if (resp.status == 504) { | |
| // Wait while an ongoing op. completes | |
| imp.wakeup(1, enableGNSS); | |
| return; | |
| } | |
| // Can't proceed any further, so report error | |
| server.error("Could not enable GNSS (" + resp.status + ")"); | |
| return; | |
| } | |
| } | |
| // GNSS is ready, so get the location | |
| getLocation(); | |
| } | |
| function getLocation() { | |
| // Use the session to get a location -- | |
| // this may not yield results immediately | |
| try { | |
| gnssSession.readposition(function(resp) { | |
| if (resp.status != 0) { | |
| // An error is indicated, but this may not be a problem | |
| if (resp.status == 516) { | |
| // Fix not yet found | |
| server.log("[DEBUG] GPS location request in progress..."); | |
| } else { | |
| server.error("GPS location request failed with error: " + resp.status); | |
| } | |
| return; | |
| } | |
| if ("quectel" in resp) { | |
| location.lat = resp.quectel.latitude; | |
| location.lon = resp.quectel.longitude; | |
| server.log(format("Device at %.4f, %.4f", location.lat.tofloat(), location.lon.tofloat())); | |
| } | |
| }.bindenv(this), 2); // '2' is the co-ordinates display mode: (-)dd.ddddd, (-)dd.ddddd | |
| } catch (error) { | |
| // Error condition | |
| server.error("Modem reported an error:"); | |
| server.log(error); | |
| } | |
| } | |
| // Enable GNSS | |
| enableGNSS(); |