Skip to main content

gnss.open(statusCallback)

Attempt to open a session to the modem’s GNSS sub-system

Availability

Device
Only available on imps with cellular modems

Parameters

Name Type Description
statusCallback Function Optional modem readiness notification handler

Returns

A gnss-session object

Description

This method is called to open a connection to a connected cellular modem’s GNSS sub-system and, if necessary, ready it for use. It returns a gnss-session object which is then used for all further interactions with the GNSS sub-system — to retrieve a location reading, for example.

The GNSS connection will remain open for as long as its gnss-session object is in scope. If gnss.open() is called again, an exception will be thrown. When the reference has gone out of scope or been manually nulled, impOS may power down the modem if it is not required for cellular communications.

Note GNSS functionality requires the presence of a SIM. There need not be a cellular connection in place, and the SIM need not be active, but a SIM must be installed, either in card or chip form-factor.

The call to gnss.open() returns the gnss-session object immediately; it does not block. However, if any of the gnss-session methods are called before the modem is ready, an exception will be thrown. Provide a status callback to be notified when GNSS is ready to use.

Note Cellular connection retries may occasionally trigger a modem power cycle. While the modem is powering up, calls to gnss-session methods may raise an exception.

The Status Callback

You may pass in a function when you call gnss.open() — it will subsequently be called whenever the state of the GNSS sub-system changes. The callback has a single parameter of its own into which will be passed a table containing a single key, ready. The key’s value is an integer that indicates the current state of the GNSS connection: either 0 (not ready) or 1 (ready).

Note Here ‘ready’ simply means that the modem is powered up and receptive to GNSS AT commands. However, the GNSS receiver may be on or off — use gnss-session.getstate() to determine the status of the GNSS sub-system itself.

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.