Merge branch 'Experimental__custom_packetCfg' into Experimental_packetBuf

Author: PaulZC

README.md

@@ -44,10 +44,10 @@ Need a library for the Ublox and Particle? Checkout the [Particle library](https
 Repository Contents
 -------------------
 
-* **/examples** - Example sketches for the library (.ino). Run these from the Arduino IDE. 
+* **/examples** - Example sketches for the library (.ino). Run these from the Arduino IDE.
 * **/src** - Source files for the library (.cpp, .h).
-* **keywords.txt** - Keywords from this library that will be highlighted in the Arduino IDE. 
-* **library.properties** - General library properties for the Arduino package manager. 
+* **keywords.txt** - Keywords from this library that will be highlighted in the Arduino IDE.
+* **library.properties** - General library properties for the Arduino package manager.
 
 Documentation
 --------------
@@ -85,9 +85,9 @@ As an example, assume that the GPS is set to produce 5 navigation
 solutions per second and that the sketch only calls getPVT once a second, then the GPS will queue 5
 packets in its internal buffer (about 500 bytes) and the library will read those when getPVT is
 called, update its internal copy of the nav data 5 times, and return `true` to the sketch. The
-skecth calls `getLatitude`, etc. and retrieve the data of the most recent of those 5 packets.
+sketch calls `getLatitude`, etc. and retrieve the data of the most recent of those 5 packets.
 
-Products That Use This Library 
+Products That Use This Library
 ---------------------------------
 
 * [GPS-15136](https://www.sparkfun.com/products/15136) - SparkFun GPS-RTK2 ZED-F9P
@@ -102,7 +102,7 @@ Products That Use This Library
 License Information
 -------------------
 
-This product is _**open source**_! 
+This product is _**open source**_!
 
 Various bits of the code have different licenses applied. Anything SparkFun wrote is beerware; if you see me (or any other SparkFun employee) at the local, and you've found our code helpful, please buy us a round!
 
@@ -111,4 +111,3 @@ Please use, reuse, and modify these files as you see fit. Please maintain attrib
 Distributed as-is; no warranty is given.
 
 - Your friends at SparkFun.
-

Theory.md

@@ -1,7 +1,7 @@
 How I2C (aka DDC) communication works with a uBlox module
 ===========================================================
 
-When the user calls one of the methods the library will poll the Ublox module for new data. 
+When the user calls one of the methods the library will poll the Ublox module for new data.
 
 * Wait for a minimum of 25 ms between polls (configured dynamically when update rate is set)
 * Write 0xFD to module
@@ -19,9 +19,14 @@ A method will call **sendCommand()**. This will begin waiting for a response wit
 
 Once **waitForACKResponse()** or **waitForNoACKResponse()** is called the library will start checking the ublox module for new bytes. These bytes may be part of a NMEA sentence, an RTCM sentence, or a UBX packet. The library will file each byte into the appropriate container. Once a given sentence or packet is complete, the appropriate processUBX(), processNMEA() will be called. These functions deal with specific processing for each type.
 
-Note: When interfacing to a ublox module over I2C the **checkUbloxI2C()** will read all bytes currently sitting in the I2C buffer. This may pick up multiple UBX packets. For example, an ACK for a VALSET may be mixed in with an auto-PVT response. We cannot tell **checkUbloxI2C()** to stop once a give ACK is found because we run the risk of leaving bytes in the I2C buffer and loosing them. We don't have this issue with **checkUbloxSerial()**.
+Note: When interfacing to a ublox module over I2C **checkUbloxI2C()** will read all bytes currently sitting in the I2C buffer. This may pick up multiple UBX packets. For example, an ACK for a VALSET may be mixed in with an auto-PVT response. We cannot tell **checkUbloxI2C()** to stop once a given ACK is found because we run the risk of leaving bytes in the I2C buffer and losing them. We don't have this issue with **checkUbloxSerial()**.
 
 **processUBX()** will check the CRC of the UBX packet. If validated, the packet will be marked as valid. Once a packet is marked as valid then **processUBXpacket()** is called to extract the contents. This is most commonly used to get the position, velocity, and time (PVT) out of the packet but is also used to check the nature of an ACK packet.
 
-Once a packet has been processed, **waitForACKResponse()/waitForNoACKResponse()** makes the appropriate decision what to do with it. If a packet satisfies the CLS/ID and characteristics of what **waitForACKResponse()/waitForNoACKResponse()** is waiting for, then it returns back to sendCommand. If the packet didn't match or was invalid then **waitForACKResponse()/waitForNoACKResponse()** will continue to wait until the correct packet is received or we time out. **sendCommand()** then returns with true/false depending on the success of **waitForACKResponse()/waitForNoACKResponse()**.
+Once a packet has been processed, **waitForACKResponse()/waitForNoACKResponse()** makes the appropriate decision what to do with it. If a packet satisfies the CLS/ID and characteristics of what **waitForACKResponse()/waitForNoACKResponse()** is waiting for, then it returns back to sendCommand. If the packet didn't match or was invalid then **waitForACKResponse()/waitForNoACKResponse()** will continue to wait until the correct packet is received or we time out. **sendCommand()** then returns with a value from the **sfe_ublox_status_e** enum depending on the success of **waitForACKResponse()/waitForNoACKResponse()**.
 
+If we are getting / polling data from the module, **sendCommand()** will return **SFE_UBLOX_STATUS_DATA_RECEIVED** if the get was successful.
+
+If we are setting / writing data to the module, **sendCommand()** will return **SFE_UBLOX_STATUS_DATA_SENT** if the set was successful.
+
+There are circumstances where the library can get the data it is expecting from the module, but it is overwritten (e.g. by an auto-PVT packet) before **sendCommand()** is able to return. In this case, **sendCommand()** will return the error **SFE_UBLOX_STATUS_DATA_OVERWRITTEN**. We should simply call the library function again, but we will need to reset the packet contents first as they will indeed have been overwritten as the error implies.

examples/Example20_SendCustomCommand/Example20_SendCustomCommand.ino

@@ -0,0 +1,189 @@
+/*
+  Send Custom Command
+  By: Paul Clark (PaulZC)
+  Date: April 18th, 2020
+
+  License: MIT. See license file for more information but you can
+  basically do whatever you want with this code.
+
+  This example shows how you can create and send a custom UBX packet
+  using the SparkFun u-blox library.
+
+  Previously it was possible to create and send a custom packet
+  through the library but it would always appear to timeout as
+  some of the internal functions referred to the internal private
+  struct packetCfg.
+  The most recent version of the library allows sendCommand to
+  use a custom packet as if it were packetCfg and so:
+  - sendCommand will return a sfe_ublox_status_e enum as if
+    it had been called from within the library
+  - the custom packet will be updated with data returned by the module
+    (previously this was not possible from outside the library)
+
+  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
+  SAM-M8Q: https://www.sparkfun.com/products/15106
+
+  Hardware Connections:
+  Plug a Qwiic cable into the GPS and a BlackBoard
+  If you don't have a platform with a Qwiic connection use the SparkFun Qwiic Breadboard Jumper (https://www.sparkfun.com/products/14425)
+  Open the serial monitor at 115200 baud to see the output
+*/
+
+#include <Wire.h> //Needed for I2C to GPS
+
+#include "SparkFun_Ublox_Arduino_Library.h" //http://librarymanager/All#SparkFun_Ublox_GPS
+SFE_UBLOX_GPS myGPS;
+
+long lastTime = 0; //Simple local timer. Limits amount if I2C traffic to Ublox module.
+
+void setup()
+{
+  Serial.begin(115200);
+  while (!Serial)
+    ; //Wait for user to open terminal
+  Serial.println("SparkFun Ublox Example");
+
+  Wire.begin();
+
+  //myGPS.enableDebugging(); // Uncomment this line to enable debug messages
+
+  if (myGPS.begin() == false) //Connect to the Ublox module using Wire port
+  {
+    Serial.println(F("Ublox GPS not detected at default I2C address. Please check wiring. Freezing."));
+    while (1)
+      ;
+  }
+
+  myGPS.setI2COutput(COM_TYPE_UBX); //Set the I2C port to output UBX only (turn off NMEA noise)
+
+  // Let's configure the module's dynamic platform model as if we were using setDynamicModel
+  // Possible values are:
+  // 0 (PORTABLE),   2 (STATIONARY), 3 (PEDESTRIAN), 4 (AUTOMOTIVE), 5 (SEA),
+  // 6 (AIRBORNE1g), 7 (AIRBORNE2g), 8 (AIRBORNE4g), 9 (WRIST),     10 (BIKE)
+
+  // Let's create our custom packet
+  uint8_t customPayload[MAX_PAYLOAD_SIZE]; // This array holds the payload data bytes
+  // The next line creates and initialises the packet information which wraps around the payload
+  ubxPacket customCfg = {0, 0, 0, 0, 0, customPayload, 0, 0, SFE_UBLOX_PACKET_VALIDITY_NOT_DEFINED, SFE_UBLOX_PACKET_VALIDITY_NOT_DEFINED};
+
+  // The structure of ubxPacket is:
+  // uint8_t cls           : The message Class
+  // uint8_t id            : The message ID
+  // uint16_t len          : Length of the payload. Does not include cls, id, or checksum bytes
+  // uint16_t counter      : Keeps track of number of overall bytes received. Some responses are larger than 255 bytes.
+  // uint16_t startingSpot : The counter value needed to go past before we begin recording into payload array
+  // uint8_t *payload      : The payload
+  // uint8_t checksumA     : Given to us by the module. Checked against the rolling calculated A/B checksums.
+  // uint8_t checksumB
+  // sfe_ublox_packet_validity_e valid            : Goes from NOT_DEFINED to VALID or NOT_VALID when checksum is checked
+  // sfe_ublox_packet_validity_e classAndIDmatch  : Goes from NOT_DEFINED to VALID or NOT_VALID when the Class and ID match the requestedClass and requestedID
+
+  // sendCommand will return:
+  // SFE_UBLOX_STATUS_DATA_RECEIVED if the data we requested was read / polled successfully
+  // SFE_UBLOX_STATUS_DATA_SENT     if the data we sent was writted successfully (ACK'd)
+  // Other values indicate errors. Please see the sfe_ublox_status_e enum for further details.
+
+  // Referring to the u-blox M8 Receiver Description and Protocol Specification we see that
+  // the dynamic model is configured using the UBX-CFG-NAV5 message. So let's load our
+  // custom packet with the correct information so we can read (poll / get) the current settings.
+
+  customCfg.cls = UBX_CLASS_CFG; // This is the message Class
+  customCfg.id = UBX_CFG_NAV5; // This is the message ID
+  customCfg.len = 0; // Setting the len (length) to zero let's us poll the current settings
+  customCfg.startingSpot = 0; // Always set the startingSpot to zero (unless you really know what you are doing)
+
+  // We also need to tell sendCommand how long it should wait for a reply
+  uint16_t maxWait = 250; // Wait for up to 250ms (Serial may need a lot longer e.g. 1100)
+
+  // Now let's read the current navigation model settings. The results will be loaded into customCfg.
+  if (myGPS.sendCommand(&customCfg, maxWait) != SFE_UBLOX_STATUS_DATA_RECEIVED) // We are expecting data and an ACK
+  {
+    Serial.println(F("sendCommand (poll / get) failed! Freezing..."));
+    while (1)
+      ;
+  }
+
+  // Referring to the message definition for UBX-CFG-NAV5 we see that we need to change
+  // byte 2 to update the dynamic platform model.
+
+  // Print the current dynamic model
+  Serial.print(F("The current dynamic model is: "));
+  Serial.print(customPayload[2]);
+
+  // Let's change it
+  if (customPayload[2] != 0x04) // If it is currently not 4, change it to 4
+  {
+    Serial.println(F(". Changing it to 4."));
+    customPayload[2] = 0x04;
+  }
+  else // If it is already 4, change it to 2
+  {
+    Serial.println(F(". Changing it to 2."));
+    customPayload[2] = 0x02;
+  }
+
+  // We don't need to update customCfg.len as it will have been set to 36 (0x24)
+  // when sendCommand read the data
+
+  // Now we write the custom packet back again to change the setting
+  if (myGPS.sendCommand(&customCfg, maxWait) != SFE_UBLOX_STATUS_DATA_SENT) // This time we are only expecting an ACK
+  {
+    Serial.println(F("sendCommand (set) failed! Freezing."));
+    while (1)
+      ;
+  }
+  else
+  {
+    Serial.println(F("Dynamic platform model updated."));
+  }
+
+  // Now let's read the navigation model settings again to see if the change was successful.
+
+  // We need to reset the packet before we try again as the values could have changed
+  customCfg.cls = UBX_CLASS_CFG;
+  customCfg.id = UBX_CFG_NAV5;
+  customCfg.len = 0;
+  customCfg.startingSpot = 0;
+
+  if (myGPS.sendCommand(&customCfg, maxWait) != SFE_UBLOX_STATUS_DATA_RECEIVED) // We are expecting data and an ACK
+  {
+    Serial.println(F("sendCommand (poll) failed! Freezing."));
+    while (1)
+      ;
+  }
+
+  // Print the current dynamic model
+  Serial.print(F("The new dynamic model is: "));
+  Serial.println(customPayload[2]);
+
+  //myGPS.saveConfigSelective(VAL_CFG_SUBSEC_NAVCONF); //Uncomment this line to save only the NAV settings to flash and BBR
+}
+
+void loop()
+{
+  //Query module only every second. Doing it more often will just cause I2C traffic.
+  //The module only responds when a new position is available
+  if (millis() - lastTime > 1000)
+  {
+    lastTime = millis(); //Update the timer
+
+    long latitude = myGPS.getLatitude();
+    Serial.print(F("Lat: "));
+    Serial.print(latitude);
+
+    long longitude = myGPS.getLongitude();
+    Serial.print(F(" Long: "));
+    Serial.print(longitude);
+    Serial.print(F(" (degrees * 10^-7)"));
+
+    long altitude = myGPS.getAltitude();
+    Serial.print(F(" Alt: "));
+    Serial.print(altitude);
+    Serial.print(F(" (mm)"));
+
+    Serial.println();
+  }
+}