To receive positioning data from the receiver in the application’s loop function it is basically just a matter of waiting for some data to be available and then get it:

void loop()
{
  /* Wait for an update. */
  if (Gnss.waitUpdate(-1))
  {
    /* Get navigation data. */
    SpNavData NavData;
    Gnss.getNavData(&NavData);

    /* Print position and satellite count. */
    Serial.print("Lat=");
    Serial.print(NavData.latitude, 6);
    Serial.print(", Lon=");
    Serial.print(NavData.longitude, 6);
    Serial.print(", Satellites=");
    Serial.print(NavData.numSatellites);
    Serial.println("");
  }
}

The waitUpdate() method will block the application and wait until some data has arrived. The parameter to the method is a timeout determining for how long it should wait if nothing is received, but when set to “-1” it will simply wait forever.

The SpNavData structure does not only contain position data (latitude, longitude and altitude) but also information about all found satellites and their status. Please see the API reference for a full description.

The GNSS module will update its positioning data once every second by default. This update rate can be modified during setup to receive updates more seldom:

void setup() {
    Gnss.begin();
    Gnss.setInterval(5);    /* Update every five seconds. */
    Gnss.start();
}

The lowest possible interval is 1 second. It cannot be set to 0, so if no more updates are wanted the GNSS module should be stopped instead.

Instead of blocking the application loop while waiting for an update, there is also the possibility to let the application poll for updated data whenever it needs it. This way you have full control of your application’s flow, but you might not always get the latest updated data depending on how your update interval is set:

void loop()
{
  /* Check for an update. */
  if (Gnss.isUpdate())
  {
    /* Get navigation data. */
    SpNavData NavData;
    Gnss.getNavData(&NavData);
  }
}

Note that this is practically the same as calling the waitUpdate() method with a timeout of 0.

The GNSS module uses GPS by default but it also supports the GLONASS and QZSS positioning with some additional satellite-based augmentation systems. The supported options are:

To, for example, add so that the application also uses GLONASS for positioning, that system has to be added in the setup using the select() method:

void setup() {
    Gnss.begin();
    Gnss.select(GLONASS);
    Gnss.start();
}

Note that this method can be called multiple times in order to select combinations of systems and augmentations.

There is also a corresponding deselect() method which works in the same way as select() but stops the GNSS module from using the given option. To check if a specific system is currently selected use isSelecting() with the given option.

When the receiver is first started it will take some time until satellites are found and a position can be determined. This delay is called TTFF (Time To First Fix). By selecting a suitable start mode and supplying initial data to the GNSS module the TTFF can be greatly reduced. Available start modes in the Arduino IDE are:

The satellite data, such as position, almanac and ephemeris, are lost when the device enters deep sleep or powers off. To speed up TTFF at next start up, these data can be saved to flash by calling Gnss.saveEphemeris(). This should only be done when positioning is deactivated. i.e. after calling Gnss.stop(). The saved data will then be automatically read and used the next time a HOT_START is triggered. It is recommended to only do this before entering deep sleep or powering off the device to not cause unnecessary wear on the flash memory.

If no mode is specified when calling start() the GNSS module will try to do use HOT_START. However, if it is not possible to reuse any data it will fall back to use COLD_START instead. This could happen if e.g. some time has passed after the data was saved since the data received from the satellite is only valid for a limited time; 2 hours for ephemeris and 90 days for the almanac.

Current time is not included in the backup data. When the module wakes up from being inactive, e.g. from the device wakes up from deep sleep, the new GPS time is calculated using the time elapsed in the Spresense RTC. At boot however, the RTC will be set to 0 so if the approximate time and date (within 60 seconds) is known to the application then it’s good to supply them before initiating a hot start. This is done using the setTime() method.

It might also be a good idea to set an initial position using setPosition() if it is believed to give a better approximation than the saved data. Note that setting time and position should be done when the receiver is in idle mode, i.e. before any positioning is started.

    # Note that this code is only a conceptual explanation for setting stored time and positioning values.
    # The values should probably not be hardcoded.
    SpGnssTime current_time;
    current_time.year = 2019;
    current_time.month = 6;
    current_time.day = 25;
    current_time.hour = 12;
    current_time.minute = 00;
    current_time.sec = 00;
    current_time.usec = 0;
    Gnss.setTime(current_time);

    double lat = 55.718272;
    double lon = 13.225060;
    double alt = 84;
    Gnss.setPosition(lat, lon, alt);

    Gnss.start(HOT_MODE);