Merge pull request #49 from sparkfun/release_candidate

v2.0.8

Author: PaulZC

README.md

@@ -17,7 +17,7 @@
   </tr>
 </table>
 
-u-blox makes some incredible GNSS receivers covering everything from low-cost, highly configurable modules such as the SAM-M8Q all the way up to the surveyor grade ZED-F9P with precision of the diameter of a dime. This library focuses on configuration and control of u-blox devices over I<sup>2</sup>C (called DDC by u-blox) and Serial. The UBX protocol is supported over both I<sup>2</sup>C and serial, and is a much easier and lighterweight interface to a GNSS module. Stop polling messages and parsing NMEA data! Simply ask for the datums you need and receive an automatic callback when they arrive.
+u-blox makes some incredible GNSS receivers covering everything from low-cost, highly configurable modules such as the SAM-M8Q all the way up to the surveyor grade ZED-F9P with precision of the diameter of a dime. This library supports configuration and control of u-blox devices over I<sup>2</sup>C (called DDC by u-blox), Serial and - as of v2.0.8 (thank you @aberridg) - SPI too! The UBX protocol is a much easier and lighterweight interface to a GNSS module. Stop polling messages and parsing NMEA data! Simply ask for the datums you need and receive an automatic callback when they arrive.
 
 This library can be installed via the Arduino Library manager. Search for **SparkFun u-blox GNSS**.
 
@@ -53,6 +53,18 @@ Migrating to v2.0 is easy. There are two small changes all users will need to ma
 
 If you are using the Dead Reckoning Sensor Fusion or High Dynamic Rate messages, you will need to make more small changes to your code. Please see the [dead reckoning examples](./examples/Dead_Reckoning) for more details. There is more detail available in [Theory.md](./Theory.md#migrating-your-code-to-v20) if you need it.
 
+## SPI Support
+
+In v2.0.8 we added support for SPI, based on a contribution by @aberridg. Thank you Andrew!
+
+We have tested the SPI interface on as many platforms and modules as we could pull together. It works perfectly on most but not quite all combinations.
+For reasons we don't understand yet, the ZED-F9P and Teensy 3.2 don't seem to get along. But Teensy 3.2 and the ZOE-M8Q do play nicely together.
+If you notice a combination that does not seem to work, please raise an [issue](https://github.com/sparkfun/SparkFun_u-blox_GNSS_Arduino_Library/issues) and we will investigate.
+
+The SPI examples have their [own folder](./examples/SPI).
+
+Please check the module datasheets for details on what clock speeds and data rates each module supports. The maximum clock speed is typically 5.5MHz and the maximum transfer rate is typically 125kBytes/s.
+
 ## Max (400kHz) I<sup>2</sup>C Support
 
 To achieve 400kHz I<sup>2</sup>C speed please be sure to remove all pull-ups on the I<sup>2</sup>C bus. Most, if not all, u-blox modules include internal pull ups on the I<sup>2</sup>C lines (sometimes called DDC in their manuals). Cut all I<sup>2</sup>C pull up jumpers and/or remove them from peripheral boards. Otherwise, various data glitches can occur. See issues [38](https://github.com/sparkfun/SparkFun_Ublox_Arduino_Library/issues/38) and [40](https://github.com/sparkfun/SparkFun_Ublox_Arduino_Library/issues/40) for more information. If possible, run the I<sup>2</sup>C bus at 100kHz.

examples/Example18_PowerSaveMode/Example18_PowerSaveMode.ino

@@ -85,22 +85,22 @@ void loop()
       if (myGNSS.powerSaveMode()) // Defaults to true
         Serial.println(F("Power Save Mode enabled."));
       else
-        Serial.println(F("***!!! Power Save Mode FAILED !!!***"));
+        Serial.println(F("*** Power Save Mode FAILED ***"));
     }
     else if (incoming == '2')
     {
       //Go to normal power mode (not power saving mode)
       if (myGNSS.powerSaveMode(false))
         Serial.println(F("Power Save Mode disabled."));
       else
-        Serial.println(F("***!!! Power Save Disable FAILED !!!***"));
+        Serial.println(F("*** Power Save Disable FAILED ***"));
     }
 
     // Read and print the new low power mode
     uint8_t lowPowerMode = myGNSS.getPowerSaveMode();
     if (lowPowerMode == 255)
     {
-      Serial.println(F("***!!! getPowerSaveMode FAILED !!!***"));
+      Serial.println(F("*** getPowerSaveMode FAILED ***"));
     }
     else
     {

examples/Example19_DynamicModel/Example19_DynamicModel.ino

@@ -68,7 +68,7 @@ void setup()
 
   if (myGNSS.setDynamicModel(DYN_MODEL_PORTABLE) == false) // Set the dynamic model to PORTABLE
   {
-    Serial.println(F("***!!! Warning: setDynamicModel failed !!!***"));
+    Serial.println(F("*** Warning: setDynamicModel failed ***"));
   }
   else
   {
@@ -79,7 +79,7 @@ void setup()
   uint8_t newDynamicModel = myGNSS.getDynamicModel();
   if (newDynamicModel == DYN_MODEL_UNKNOWN)
   {
-    Serial.println(F("***!!! Warning: getDynamicModel failed !!!***"));
+    Serial.println(F("*** Warning: getDynamicModel failed ***"));
   }
   else
   {

examples/Example1_BasicNMEARead/Example1_BasicNMEARead.ino

@@ -39,6 +39,9 @@ void setup()
     while (1);
   }
 
+  myGNSS.setI2COutput(COM_TYPE_UBX | COM_TYPE_NMEA); //Set the I2C port to output both NMEA and UBX messages
+  myGNSS.saveConfigSelective(VAL_CFG_SUBSEC_IOPORT); //Save (only) the communications port settings to flash and BBR
+
   //This will pipe all NMEA sentences to the serial port so we can see them
   myGNSS.setNMEAOutputPort(Serial);
 }

examples/Example24_GetUnixEpochAndMicros/Example24_GetUnixEpochAndMicros.ino

@@ -91,6 +91,12 @@ void loop()
     Serial.print(myGNSS.getSecond());
 
     Serial.print("  Time is ");
+    if (myGNSS.getTimeFullyResolved() == false)
+    {
+      Serial.print("not fully resolved but ");
+    } else {
+      Serial.print("fully resolved and ");
+    }
     if (myGNSS.getTimeValid() == false)
     {
       Serial.print("not ");

examples/Example2_NMEAParsing/Example2_NMEAParsing.ino

@@ -46,6 +46,9 @@ void setup()
     while (1);
   }
 
+  myGNSS.setI2COutput(COM_TYPE_UBX | COM_TYPE_NMEA); //Set the I2C port to output both NMEA and UBX messages
+  myGNSS.saveConfigSelective(VAL_CFG_SUBSEC_IOPORT); //Save (only) the communications port settings to flash and BBR
+
   myGNSS.setProcessNMEAMask(SFE_UBLOX_FILTER_NMEA_ALL); // Make sure the library is passing all NMEA messages to processNMEA
 
   myGNSS.setProcessNMEAMask(SFE_UBLOX_FILTER_NMEA_GGA); // Or, we can be kind to MicroNMEA and _only_ pass the GGA messages to it

examples/SPI/Example1_GetPosition/Example1_GetPosition.ino

@@ -0,0 +1,123 @@
+/*
+  Reading lat and long via UBX binary commands over SPI
+  By: Andrew Berridge
+  Date: 27th June 2021
+  License: MIT. See license file for more information but you can
+  basically do whatever you want with this code.
+
+  This example shows how to query a u-blox module for its lat/long/altitude over SPI. We also
+  turn off the NMEA output on the SPI port. This decreases the amount of SPI traffic 
+  dramatically.
+
+  Note: Long/lat are large numbers because they are * 10^7. To convert lat/long
+  to something google maps understands simply divide the numbers by 10,000,000. We 
+  do this so that we don't have to use floating point numbers.
+
+  Leave NMEA parsing behind. Now you can simply ask the module for the datums you want!
+
+  Feel like supporting open source hardware?
+  Buy a board from SparkFun!
+  ZED-F9P RTK2: https://www.sparkfun.com/products/15136
+  NEO-M8P RTK: https://www.sparkfun.com/products/15005
+  NEO-M8U: https://www.sparkfun.com/products/16329
+  NEO-M9N: https://www.sparkfun.com/products/17285
+
+  Hardware Connections:
+  You need to connect the SPI pins from your microcontroller to the specific pins on your SparkFun product. 
+  Connections will vary based on your microcontroller, but for reference please refer to this tutorial on SPI:
+  https://learn.sparkfun.com/tutorials/serial-peripheral-interface-spi/all
+  
+  Most new boards now use the terms:
+  CS - Chip Select
+  COPI - Controller Out, Peripheral In
+  CIPO - Controller in, Peripheral Out
+  SCK - Serial Clock
+
+  You can choose any pin for Chip Select, but the others are likely either defined by the library you are using
+  (see here for the standard Arduino one: https://www.arduino.cc/en/reference/SPI) or the microcontroller. The
+  ESP32 has two standard, selectable SPI ports, for example.
+
+  To enable SPI communication, you will need to solder the DSEL/SPI jumper closed on your u-blox board.
+
+  IMPORTANT: there have been reports that some u-blox devices do not respond to the UBX protocol over SPI
+  with the factory settings. You may find you need to connect to the device via USB and u-center and set
+  the incoming protocol to UBX only. Make sure you disable all other protocols as inputs if you can't
+  get things to work! Hopefully this is just a bug in the u-blox firmware that will be fixed soon ;-)
+
+*/
+
+#include <SPI.h> //Needed for SPI to GNSS
+
+#include <SparkFun_u-blox_GNSS_Arduino_Library.h> //http://librarymanager/All#SparkFun_u-blox_GNSS
+SFE_UBLOX_GNSS myGNSS;
+
+// #########################################
+
+// Instantiate an instance of the SPI class. 
+// Your configuration may be different, depending on the microcontroller you are using!
+
+#define spiPort SPI // This is the SPI port on standard Ardino boards. Comment this line if you want to use a different port.
+
+//SPIClass spiPort (HSPI); // This is the default SPI interface on some ESP32 boards. Uncomment this line if you are using ESP32.
+
+// #########################################
+
+const uint8_t csPin = 10; // On ATmega328 boards, SPI Chip Select is usually pin 10. Change this to match your board.
+
+// #########################################
+
+long lastTime = 0; //Simple local timer. Limits amount of SPI traffic to u-blox module.
+
+void setup()
+{
+  Serial.begin(115200);
+  while (!Serial); //Wait for user to open terminal
+  Serial.println(F("SparkFun u-blox Example"));
+
+  spiPort.begin(); // begin the SPI port
+
+  //myGNSS.enableDebugging(); // Uncomment this line to see helpful debug messages on Serial
+
+  // Connect to the u-blox module using SPI port, csPin and speed setting
+  // ublox devices generally work up to 5MHz. We'll use 4MHz for this example:
+  if (myGNSS.begin(spiPort, csPin, 4000000) == false) 
+  {
+    Serial.println(F("u-blox GNSS not detected on SPI bus. Please check wiring. Freezing."));
+    while (1);
+  }
+  
+  //myGNSS.factoryDefault(); delay(5000); // Uncomment this line to reset the module back to its factory defaults
+
+  myGNSS.setPortOutput(COM_PORT_SPI, COM_TYPE_UBX); //Set the SPI port to output UBX only (turn off NMEA noise)
+  myGNSS.saveConfigSelective(VAL_CFG_SUBSEC_IOPORT); //Save (only) the communications port settings to flash and BBR
+}
+
+void loop()
+{
+  //Query module only every second. Doing it more often will just cause SPI traffic.
+  //The module only responds when a new position is available
+  if (millis() - lastTime > 1000)
+  {
+    lastTime = millis(); //Update the timer
+    
+    long latitude = myGNSS.getLatitude();
+    Serial.print(F("Lat: "));
+    Serial.print(latitude);
+
+    long longitude = myGNSS.getLongitude();
+    Serial.print(F(" Long: "));
+    Serial.print(longitude);
+    Serial.print(F(" (degrees * 10^-7)"));
+
+    long altitude = myGNSS.getAltitude();
+    Serial.print(F(" Alt: "));
+    Serial.print(altitude);
+    Serial.print(F(" (mm)"));
+
+    byte SIV = myGNSS.getSIV();
+    Serial.print(F(" SIV: "));
+    Serial.print(SIV);
+
+    Serial.println();
+  }
+}