gnss.open(statusCallback)

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.