[LR11x0] GNSS support (#1275)

* [LR11x0] Added WIP GNSS control

* [LR11x0] Added almanac update

* [LR11x0] Added almanac update example

* [LR11x0] Add missing memory deallocation

* [LR11x0] Fix underflow in delay until subframe

* [LR11x0] Remove pin mapping from example

* [LR11x0] Finish rework of the GNSS API

* [LR11x0] Added position and satellite examples

* [LR11x0] Fix result member in example

* Added LR11x0 GNSS keywords

* [LR11x0] Fix typo in macro name

* [LR11x0] Print scan failed in example

* [LR11x0] Added GNSS abort

examples/LR11x0/LR11x0_GNSS_Almanac_Update/LR11x0_GNSS_Almanac_Update.ino

@@ -0,0 +1,151 @@
+/*
+  RadioLib LR11x0 GNSS Almanac Update Example
+
+  This example updates the LR11x0 GNSS almanac.
+  Almanac is a database of orbital predictions of 
+  GNSS satellites, which allows the module to predict
+  when different satellites will appear in the sky,
+  and frequency of their signal.
+  
+  Up-to-date almanac is necessary for operation!
+  After an update, data will remain valid for 30 days.
+  All GNSS examples require at least limited
+  visibility of the sky!
+
+  NOTE: This example will only work for LR11x0 devices
+        with sufficiently recent firmware!
+        LR1110: 4.1
+        LR1120: 2.1
+        If your device firmware reports older firmware,
+        update it using the LR11x0_Firmware_Update example.
+
+  For full API reference, see the GitHub Pages
+  https://jgromes.github.io/RadioLib/
+*/
+
+// include the library
+#include <RadioLib.h>
+
+// LR1110 has the following connections:
+// NSS pin:   10
+// DIO1 pin:  2
+// NRST pin:  3
+// BUSY pin:  9
+LR1110 radio = new Module(10, 2, 3, 9);
+
+// structure to save information about the GNSS almanac
+LR11x0GnssAlmanacStatus_t almStatus;
+
+void setup() {
+  Serial.begin(9600);
+
+  // initialize LR1110 with default settings
+  Serial.print(F("[LR1110] Initializing ... "));
+  int state = radio.beginGNSS(RADIOLIB_LR11X0_GNSS_CONSTELLATION_GPS);
+  if (state == RADIOLIB_ERR_NONE) {
+    Serial.println(F("success!"));
+  } else {
+    Serial.print(F("failed, code "));
+    Serial.println(state);
+    while (true) { delay(10); }
+  }
+
+  // check the firmware version
+  Serial.print(F("[LR1110] Checking firmware version ... "));
+  state = radio.isGnssScanCapable();
+  if (state == RADIOLIB_ERR_NONE) {
+    Serial.println(F("check passed!"));
+  } else {
+    Serial.println(F("check failed, firmware update needed."));
+    while (true) { delay(10); }
+  }
+
+  // run GNSS scans until we get at least the time
+  // NOTE: Depending on visibility of satellites,
+  //       this may take multiple attempts!
+  while(true) {
+    // run GNSS scan
+    Serial.print(F("[LR1110] Running GNSS scan ... "));
+    state = radio.gnssScan(NULL);
+    if (state == RADIOLIB_ERR_NONE) {
+      Serial.println(F("success!"));
+    } else {
+      Serial.print(F("failed, code "));
+      Serial.println(state);
+      while (true) { delay(10); }
+    }
+
+    // check almanac status
+    Serial.print(F("[LR1110] Checking GNSS almanac ... "));
+    state = radio.getGnssAlmanacStatus(&almStatus);
+    if (state != RADIOLIB_ERR_NONE) {
+      Serial.print(F("failed, code "));
+      Serial.println(state);
+      while (true) { delay(10); }
+    }
+
+    // we have the status, check if we have demodulated time
+    if(almStatus.gps.status < RADIOLIB_LR11X0_GNSS_ALMANAC_STATUS_UP_TO_DATE) {
+      Serial.println(F("time unknown, another scan needed."));
+
+    } else if(almStatus.gps.numUpdateNeeded > 0) {
+      Serial.print(almStatus.gps.numUpdateNeeded);
+      Serial.println(F(" satellites out-of-date."));
+      break;
+
+    } else {
+      Serial.println(F("no update needed!"));
+      while (true) { delay(10); }
+
+    }
+  }
+}
+
+void loop() {
+  // wait until almanac data is available in the signal
+  // multiple attempts are needed for this
+  Serial.print(F("[LR1110] Waiting for subframe ... "));
+  int state = radio.gnssDelayUntilSubframe(&almStatus, RADIOLIB_LR11X0_GNSS_CONSTELLATION_GPS);
+  if(state == RADIOLIB_ERR_GNSS_SUBFRAME_NOT_AVAILABLE) {
+    Serial.println(F("not enough time left."));
+
+    // wait until the next update window
+    delay(2000);
+
+  } else {
+    Serial.println(F("done!"));
+
+    // we have enough time to start the update
+    Serial.print(F("[LR1110] Starting update ... "));
+    state = radio.updateGnssAlmanac(RADIOLIB_LR11X0_GNSS_CONSTELLATION_GPS);
+    if(state != RADIOLIB_ERR_NONE) {
+      Serial.print(F("failed, code "));
+      Serial.println(state);
+    } else {
+      Serial.println(F("done!"));
+    }
+
+  }
+
+  // check whether another update is needed
+  Serial.print(F("[LR1110] Checking GNSS almanac ... "));
+  state = radio.getGnssAlmanacStatus(&almStatus);
+  if(state != RADIOLIB_ERR_NONE) {
+    Serial.print(F("failed, code "));
+    Serial.println(state);
+    while (true) { delay(10); }
+  }
+
+  // check if we have completed the update
+  if(almStatus.gps.numUpdateNeeded == 0) {
+    Serial.println(F("all satellites up-to-date!"));
+    while (true) { delay(10); }
+  } else {
+    Serial.print(almStatus.gps.numUpdateNeeded);
+    Serial.println(F(" satellites out-of-date."));
+  }
+
+  // wait a bit before the next update attempt
+  delay(1000);
+
+}

examples/LR11x0/LR11x0_GNSS_Autonomous_Position/LR11x0_GNSS_Autonomous_Position.ino

@@ -0,0 +1,103 @@
+/*
+  RadioLib LR11x0 GNSS Autonomous Position Example
+
+  This example performs GNSS scans and calculates
+  position of the device using autonomous mode.
+  In this mode, scan data does not need to be uploaded
+  to LoRaCloud, however, it requires up-to-date almanac
+  data. Run the LR11x0_Almanac_Update example to update
+  the device almanac.
+
+  NOTE: This example will only work for LR11x0 devices
+        with sufficiently recent firmware!
+        LR1110: 4.1
+        LR1120: 2.1
+        If your device firmware reports older firmware,
+        update it using the LR11x0_Firmware_Update example.
+
+  For full API reference, see the GitHub Pages
+  https://jgromes.github.io/RadioLib/
+*/
+
+// include the library
+#include <RadioLib.h>
+
+// LR1110 has the following connections:
+// NSS pin:   10
+// DIO1 pin:  2
+// NRST pin:  3
+// BUSY pin:  9
+LR1110 radio = new Module(10, 2, 3, 9);
+
+// structure to save information about the GNSS scan result
+LR11x0GnssResult_t gnssResult;
+
+// structure to save information about the calculated GNSS position
+LR11x0GnssPosition_t gnssPosition;
+
+void setup() {
+  Serial.begin(9600);
+
+  // initialize LR1110 with default settings
+  Serial.print(F("[LR1110] Initializing ... "));
+  int state = radio.beginGNSS(RADIOLIB_LR11X0_GNSS_CONSTELLATION_GPS);
+  if (state == RADIOLIB_ERR_NONE) {
+    Serial.println(F("success!"));
+  } else {
+    Serial.print(F("failed, code "));
+    Serial.println(state);
+    while (true) { delay(10); }
+  }
+
+  // check the firmware version
+  Serial.print(F("[LR1110] Checking firmware version ... "));
+  state = radio.isGnssScanCapable();
+  if (state == RADIOLIB_ERR_NONE) {
+    Serial.println(F("check passed!"));
+  } else {
+    Serial.println(F("check failed, firmware update needed."));
+    while (true) { delay(10); }
+  }
+
+  Serial.println(F("Scan result\t| Latitude\t| Longitude\t| Accuracy\t| Number of satellites"));
+}
+
+void loop() {
+  // run GNSS scan
+  int state = radio.gnssScan(&gnssResult);
+  if(state == RADIOLIB_ERR_NONE) {
+    // success!
+    Serial.print(gnssResult.demodStat); Serial.print("\t\t| ");
+
+    // get the actual data
+    state = radio.getGnssPosition(&gnssPosition);
+    if(state == RADIOLIB_ERR_NONE) {
+      // print the position
+      Serial.print(gnssPosition.latitude, 6);
+      Serial.print("\t| ");
+      Serial.print(gnssPosition.longitude, 6);
+      Serial.print("\t| ");
+      Serial.print(gnssPosition.accuracy);
+      Serial.print("\t\t| ");
+      Serial.println(gnssPosition.numSatsUsed);
+
+    } else {
+      Serial.print(F("Failed to read result, code "));
+      Serial.print(state);
+      Serial.print(F(" (solver error "));
+      Serial.print(RADIOLIB_GET_GNSS_SOLVER_ERROR(state));
+      Serial.println(F(")"));
+    }
+
+  } else {
+    Serial.print(F("Scan failed, code "));
+    Serial.print(state);
+    Serial.print(F(" (demodulator error "));
+    Serial.print(RADIOLIB_GET_GNSS_DEMOD_ERROR(state));
+    Serial.println(F(")"));
+
+  }
+
+  // wait a bit before the next scan
+  delay(1000);
+}

examples/LR11x0/LR11x0_GNSS_Satellites/LR11x0_GNSS_Satellites.ino

@@ -0,0 +1,102 @@
+/*
+  RadioLib LR11x0 GNSS Satellites Example
+
+  This example performs GNSS scans and shows the satellites
+  currently in view. It is mostly useful to verify
+  visibility and antenna setup.
+
+  NOTE: This example will only work for LR11x0 devices
+        with sufficiently recent firmware!
+        LR1110: 4.1
+        LR1120: 2.1
+        If your device firmware reports older firmware,
+        update it using the LR11x0_Firmware_Update example.
+
+  For default module settings, see the wiki page
+  https://github.com/jgromes/RadioLib/wiki/Default-configuration#lr11x0---wifi-scan
+
+  For full API reference, see the GitHub Pages
+  https://jgromes.github.io/RadioLib/
+*/
+
+// include the library
+#include <RadioLib.h>
+
+// LR1110 has the following connections:
+// NSS pin:   10
+// DIO1 pin:  2
+// NRST pin:  3
+// BUSY pin:  9
+LR1110 radio = new Module(10, 2, 3, 9);
+
+// structure to save information about the GNSS scan result
+LR11x0GnssResult_t gnssResult;
+
+void setup() {
+  Serial.begin(9600);
+
+  // initialize LR1110 with default settings
+  Serial.print(F("[LR1110] Initializing ... "));
+  int state = radio.beginGNSS(RADIOLIB_LR11X0_GNSS_CONSTELLATION_GPS);
+  if (state == RADIOLIB_ERR_NONE) {
+    Serial.println(F("success!"));
+  } else {
+    Serial.print(F("failed, code "));
+    Serial.println(state);
+    while (true) { delay(10); }
+  }
+
+  // check the firmware version
+  Serial.print(F("[LR1110] Checking firmware version ... "));
+  state = radio.isGnssScanCapable();
+  if (state == RADIOLIB_ERR_NONE) {
+    Serial.println(F("check passed!"));
+  } else {
+    Serial.println(F("check failed, firmware update needed."));
+    while (true) { delay(10); }
+  }
+}
+
+void loop() {
+  Serial.print(F("[LR1110] Running GNSS scan ... "));
+  int state = radio.gnssScan(&gnssResult);
+  if(state != RADIOLIB_ERR_NONE) {
+    // some error occurred
+    Serial.print(F("failed, code "));
+    Serial.print(state);
+    Serial.print(F(" (demodulator error "));
+    Serial.print(RADIOLIB_GET_GNSS_DEMOD_ERROR(state));
+    Serial.println(F(")"));
+
+  } else  {
+    Serial.println(F("success!"));
+
+    // print the table header
+    Serial.print(F("[LR1110] Detected "));
+    Serial.print(gnssResult.numSatsDet);
+    Serial.println(F(" satellite(s):"));
+    Serial.println(F(" # | ID | C/N0 [dB]\t| Doppler [Hz]"));
+
+    // read all results at once
+    LR11x0GnssSatellite_t satellites[32];
+    state = radio.getGnssSatellites(satellites, gnssResult.numSatsDet);
+    if(state != RADIOLIB_ERR_NONE) {
+      Serial.print(F("Failed to read results, code "));
+      Serial.println(state);
+    } else {
+      // print all the results
+      for(int i = 0; i < gnssResult.numSatsDet; i++) {
+        if(i < 10) { Serial.print(" "); } Serial.print(i); Serial.print(" | ");
+        Serial.print(satellites[i].svId); Serial.print(" | ");
+        Serial.print(satellites[i].c_n0); Serial.print("\t\t| ");
+        Serial.println(satellites[i].doppler);
+
+      }
+
+    }
+
+  }
+
+  // wait for a second before scanning again
+  delay(1000);
+}

keywords.txt

@@ -100,6 +100,11 @@ LR11x0WifiResult_t	KEYWORD1
 LR11x0WifiResultFull_t	KEYWORD1
 LR11x0WifiResultExtended_t	KEYWORD1
 LR11x0VersionInfo_t	KEYWORD1
+LR11x0GnssResult_t	KEYWORD1
+LR11x0GnssPosition_t	KEYWORD1
+LR11x0GnssSatellite_t	KEYWORD1
+LR11x0GnssAlmanacStatusPart_t	KEYWORD1
+LR11x0GnssAlmanacStatus_t	KEYWORD1
 
 #######################################
 # Methods and Functions (KEYWORD2)
@@ -261,6 +266,14 @@ setWiFiScanAction	KEYWORD2
 clearWiFiScanAction	KEYWORD2
 getVersionInfo	KEYWORD2
 updateFirmware	KEYWORD2
+beginGNSS	KEYWORD2
+isGnssScanCapable	KEYWORD2
+gnssScan	KEYWORD2
+getGnssAlmanacStatus	KEYWORD2
+gnssDelayUntilSubframe	KEYWORD2
+updateGnssAlmanac	KEYWORD2
+getGnssPosition	KEYWORD2
+getGnssSatellites	KEYWORD2
 
 # RTTY
 idle	KEYWORD2
@@ -473,6 +486,12 @@ RADIOLIB_ERR_SESSION_DISCARDED	LITERAL1
 RADIOLIB_ERR_INVALID_MODE	LITERAL1
 
 RADIOLIB_ERR_INVALID_WIFI_TYPE	LITERAL1
+RADIOLIB_ERR_GNSS_SUBFRAME_NOT_AVAILABLE	LITERAL1
+RADIOLIB_GET_GNSS_DEMOD_ERROR	LITERAL1
+RADIOLIB_GET_GNSS_SOLVER_ERROR	LITERAL1
+RADIOLIB_LR11X0_GNSS_CONSTELLATION_GPS	LITERAL1
+RADIOLIB_LR11X0_GNSS_CONSTELLATION_BEIDOU	LITERAL1
+RADIOLIB_LR11X0_GNSS_ALMANAC_STATUS_UP_TO_DATE	LITERAL1
 
 RADIOLIB_LR1110_FIRMWARE_IN_RAM	LITERAL1
 RADIOLIB_LR11X0_FIRMWARE_IMAGE_SIZE	LITERAL1