v0.1.1

* Updated documentation.
* Fixed variable name issues.

Changes.md

@@ -1,6 +1,12 @@
 
-**+05:30 11:42:21 PM 12-07-2023, Wednesday**
+### **+05:30 12:28:04 AM 13-07-2023, Thursday**
+
+  * Updated documentation.
+  * Fixed variable name issues.
+  * Version 🆕 `0.1.1`.
+
+### **+05:30 11:42:21 PM 12-07-2023, Wednesday**
 
   * First commit.
-  * Version 0.1.0.
+  * Version 🆕 `0.1.0`.
 

library.json

@@ -13,7 +13,7 @@
         "url": "https://github.com/vishnumaiea",
         "maintainer": true
     },
-    "version": "0.1.0",
+    "version": "0.1.1",
     "license": "MIT",
     "frameworks": "arduino",
     "platforms": "*"

library.properties

@@ -1,5 +1,5 @@
 name=CSE_GNSS
-version=0.1.0
+version=0.1.1
 author=Vishnu Mohanan
 maintainer=Vishnu Mohanan
 sentence=Arduino library for reading and writing NMEA-supported GNSS/GPS modules.

src/CSE_GNSS.cpp

@@ -3,8 +3,8 @@
 /**
  * @file CSE_GNSS.cpp
  * @brief Main source file for CSE_GNSS library.
- * @date +05:30 04:34:13 PM 10-07-2023, Monday
- * @version 0.1.0
+ * @date +05:30 12:16:10 AM 13-07-2023, Thursday
+ * @version 0.1.1
  * @author Vishnu Mohanan (@vishnumaiea)
  * @par GitHub Repository: https://github.com/CIRCUITSTATE/CSE_GNSS
  * @par MIT License
@@ -19,7 +19,7 @@
  * @brief NMEA_0183_Data constructor.
  * 
  * @param name The name of the NMEA sentence.eg. "GPRMC".
- * @param dataCount The number of data in the NMEA sentence.
+ * @param dataCount The number of data fields in the NMEA sentence.
  * @param sample A sample string of the NMEA sentence.
  * @return NMEA_0183_Data:: 
  */
@@ -89,7 +89,7 @@ bool NMEA_0183_Data:: parse() {
 /**
  * @brief Set the NMEA sentence.
  * 
- * @param line A valid NMEA sentence.
+ * @param line A valid NMEA sentence. Not checked for validity.
  * @return true If setting was successful.
  * @return false If setting was not successful.
  */
@@ -173,31 +173,27 @@ bool NMEA_0183_Data:: check (String line) {
 
 //======================================================================================//
 /**
- * @brief Find the NMEA sentence in the given lines. Only the first found NMEA of the given
- * type is read. If your GNSS module outputs 10 lines every second, then you should at least
- * read 11 line so that you get all complete lines at least once. Do not remove the newline
- * character from the lines. After finding a valid line, the data is extracted and saved in
- * the object.
+ * @brief Find the particular NMEA sentence from the given lines. The lines have to 
+ * separated by a newline character. Some NMEA sentences can have multiple lines.
+ * In that case, you can specify which occurrence of the NMEA sentence you want to find.
+ * If the occurrence is not specified, the first occurrence will be returned.
  * 
- * The position of the given NMEA line can be used to specify which line to read if there are
- * multiple consecutive lines of the same type. This is useful for reading lines like GPGSA.
- * 
- * @param lines The lines as a String.
- * @param position The position of the given NMEA line to read. Default is 0.
+ * @param lines The lines as a String separated by a newline character.
+ * @param occurrence The occurrence of the given NMEA line to read. Default is 0.
  * @return true Data was successfully parsed and saved.
  * @return false No valid line was found.
  */
-bool NMEA_0183_Data:: find (String lines, int position) {
-  if ((position < 0) || (position > 63)) {
+bool NMEA_0183_Data:: find (String lines, int occurrence) {
+  if ((occurrence < 0) || (occurrence > 63)) {
     GNSS_Parent->Debug_Serial->println ("NMEA_0183_Data find(): Invalid position.");
     return false;
   }
 
   String splittedLines [64] = {""};
   int startIndex = 0;
   int lineCount = 0;  // Total number of lines.
-  int instanceCount = -1; // The number of instances of the given NMEA type.
-  int instanceIndex = -1; // The index of the given NMEA type in the lines array.
+  int occurrenceCount = -1; // The number of instances/occurrence of the given NMEA type in the lines.
+  int occurrenceIndex = -1; // The index of the given NMEA type in the lines array.
 
   // Split the lines to an array.
   for (int i = 0; i < lines.length(); i++) {
@@ -235,35 +231,35 @@ bool NMEA_0183_Data:: find (String lines, int position) {
   // Check if any lines starts with the given NMEA ID.
   for (int i = 0; i < lineCount; i++) {
     if ((splittedLines [i].startsWith (name)) || (splittedLines [i].startsWith (String ("$") + name))) {
-      instanceCount += 1;
+      occurrenceCount += 1;
     }
 
-    // Break if we find the line at the position we want.
-    if (instanceCount == position) {
-      instanceIndex = i;
+    // Break if we find the line at the same occurrence we want.
+    if (occurrenceCount == occurrence) {
+      occurrenceIndex = i;
       break;
     }
   }
 
   // Return false if no valid line was found.
-  if (instanceCount == -1) {
-    GNSS_Parent->Debug_Serial->println ("NMEA_0183_Data find(): No valid line found.");
+  if (occurrenceCount == -1) {
+    GNSS_Parent->Debug_Serial->println ("NMEA_0183_Data find(): No valid lines found.");
     return false;
   }
 
-  // If the instanceCount is not -1, but less than the position, that means there was at least one
+  // If the occurrenceCount is not -1, but less than the position, that means there was at least one
   // line, but not enough to reach the position. For example if you wanted to get the 2nd
-  // GPGSV message in the lines, but there was only one, then the instanceCount would be 0.
-  if (instanceCount < position) {
+  // GPGSV message in the lines, but there was only one, then the occurrenceCount would be 0.
+  if (occurrenceCount < occurrence) {
     GNSS_Parent->Debug_Serial->println ("NMEA_0183_Data find(): Not enough lines to reach the position.");
-    GNSS_Parent->Debug_Serial->println ("NMEA_0183_Data find(): instanceCount: " + String (instanceCount));
+    GNSS_Parent->Debug_Serial->println ("NMEA_0183_Data find(): occurrenceCount: " + String (occurrenceCount));
     return false;
   }
 
-  // If the instanceCount is equal to the position, then we have found the line we want.
-  if (instanceCount == position) {
-    GNSS_Parent->Debug_Serial->println ("NMEA_0183_Data find(): Found " + name + " line at position " + String (instanceCount));
-    set (splittedLines [instanceIndex]);
+  // If the occurrenceCount is equal to the occurrence, then we have found the line we want.
+  if (occurrenceCount == occurrence) {
+    GNSS_Parent->Debug_Serial->println ("NMEA_0183_Data find(): Found " + name + " line at position " + String (occurrenceCount));
+    set (splittedLines [occurrenceIndex]);
     return parse();
   }
 
@@ -281,7 +277,7 @@ int NMEA_0183_Data:: count (String lines) {
   String splittedLines [64] = {""};
   int startIndex = 0;
   int lineCount = 0;
-  int instanceCountCount = 0;
+  int instanceCount = 0;
 
   // Split the lines to an array.
   for (int i = 0; i < lines.length(); i++) {
@@ -296,13 +292,13 @@ int NMEA_0183_Data:: count (String lines) {
   // Check if any lines starts with the given NMEA ID.
   for (int i = 0; i < lineCount; i++) {
     if ((splittedLines [i].startsWith (name)) || (splittedLines [i].startsWith (String ("$") + name))) {
-      instanceCountCount += 1;
+      instanceCount += 1;
     }
   }
 
-  GNSS_Parent->Debug_Serial->println ("NMEA_0183_Data count(): Found " + String (instanceCountCount) + " " + name + " lines.");
+  GNSS_Parent->Debug_Serial->println ("NMEA_0183_Data count(): Found " + String (instanceCount) + " " + name + " lines.");
 
-  return instanceCountCount;
+  return instanceCount;
 }
 
 //======================================================================================//
@@ -342,6 +338,7 @@ CSE_GNSS:: CSE_GNSS (HardwareSerial* gnssSerial, HardwareSerial* debugSerial, ui
   this->gnssBaud = gnssBaud;
   this->debugBaud = debugBaud;
 
+  // Add data to the dummy data object.
   static String NMEA_Sample = "$DUMMY,120556.096,V,123.456,N,123.456,E,1.23,123.45,020723,1.9,W,N,V*33";
   static String NMEA_Data_Names [] = {"Header", "UTC", "Status", "Latitude", "Latitude Direction", "Longitude", "Longitude Direction", "Speed", "Course", "Date", "Mag Variation", "Mag Variation Direction", "Mode", "Second Mode", "Checksum"};
   static String NMEA_Description = "You forgot to add NMEA_0183_Data objects. Please add at least one.";
@@ -352,7 +349,7 @@ CSE_GNSS:: CSE_GNSS (HardwareSerial* gnssSerial, HardwareSerial* debugSerial, ui
 //======================================================================================//
 
 // Only for software serial.
-#if defined(__AVR__) || defined(ESP8266)
+#if SOFTWARE_SERIAL_REQUIRED
   /**
    * @brief Construct a new CSE_GNSS object with software serial port for GNSS module.
    * Debug serial port is still hardware serial. The baudrates are optional. The ports
@@ -371,6 +368,7 @@ CSE_GNSS:: CSE_GNSS (HardwareSerial* gnssSerial, HardwareSerial* debugSerial, ui
   this->gnssBaud = gnssBaud;
   this->debugBaud = debugBaud;
 
+  // Add data to the dummy data object.
   static String NMEA_Sample = "$DUMMY,120556.096,V,123.456,N,123.456,E,1.23,123.45,020723,1.9,W,N,V*33";
   static String NMEA_Data_Names [] = {"Header", "UTC", "Status", "Latitude", "Latitude Direction", "Longitude", "Longitude Direction", "Speed", "Course", "Date", "Mag Variation", "Mag Variation Direction", "Mode", "Second Mode", "Checksum"};
   static String NMEA_Description = "You forgot to add NMEA_0183_Data objects. Please add at least one.";
@@ -549,7 +547,7 @@ int CSE_GNSS:: addData (NMEA_0183_Data* data) {
 //======================================================================================//
 /**
  * @brief Returns the reference to the NMEA_0183_Data object with the given name. If no
- * data with the given name is found, an exception is thrown.
+ * data with the given name is found, a dummy data is returned.
  * 
  * @param name The name of the NMEA_0183_Data object. For example, "GPRMC".
  * @return CSE_GNSS::NMEA_0183_Data_Ref 

src/CSE_GNSS.h

@@ -3,8 +3,8 @@
 /**
  * @file CSE_GNSS.h
  * @brief Main header file for CSE_GNSS library.
- * @date +05:30 04:34:13 PM 10-07-2023, Monday
- * @version 0.1.0
+ * @date +05:30 12:16:15 AM 13-07-2023, Thursday
+ * @version 0.1.1
  * @author Vishnu Mohanan (@vishnumaiea)
  * @par GitHub Repository: https://github.com/CIRCUITSTATE/CSE_GNSS
  * @par MIT License
@@ -18,7 +18,10 @@
 #include <Arduino.h>
 #include <vector>
 
-#if defined(__AVR__) || defined(ESP8266)
+// You can expand the software serial support here.
+#define SOFTWARE_SERIAL_REQUIRED defined(__AVR__) || defined(ESP8266)
+
+#if SOFTWARE_SERIAL_REQUIRED
   #include <SoftwareSerial.h> //software serial doesn't work with Arduino Due
 #endif
 
@@ -37,13 +40,13 @@ class NMEA_0183_Data {
     CSE_GNSS* GNSS_Parent; // The parent GNSS object
 
     String name; // NMEA sentence type/name
-    String description; // NMEA sentence description
+    String description; // User-redable NMEA sentence description
     String sentence; // Comma separated NMEA sentence
     String sample; // NMEA sentence sample
     int dataCount; // Number of data in the NMEA sentence, including the header and separate checksum
-    const static int dataMax = 64; // Maximum number of data in the NMEA sentence
-    String dataList [dataMax]; // NMEA sentence data
-    String dataNameList [dataMax]; // NMEA sentence data name
+    const static int dataMax = 64; // Maximum number of data fields in the NMEA sentence
+    String dataList [dataMax]; // NMEA data fields as an array of strings
+    String dataNameList [dataMax]; // NMEA data field names as an array of strings
 
     NMEA_0183_Data (String name, String description, int dataCount, String dataNames[], String sample);
     bool parse(); // Parse the NMEA sentence
@@ -52,25 +55,29 @@ class NMEA_0183_Data {
     bool check (String line); // Check if the NMEA sentence is valid
     bool find (String lines, int position = 0); // Find the NMEA sentence in the lines
     int count (String lines); // Count the number of particular NMEA sentence in the lines
-    int getDataIndex (String dataName); // Get the index of the dataName
+    int getDataIndex (String dataName); // Get the index of the data field name
 };
 
 //======================================================================================//
-
+/**
+ * @brief A generic class to read and write GNSS modules with serial interface. Supports
+ * hardware serial for debug messages and either hardware/software serial for the GNSS.
+ * 
+ */
 class CSE_GNSS {
   private:
     friend class NMEA_0183_Data;
 
     HardwareSerial* Debug_Serial; // The serial port of the debug monitor.
 
-    #if defined(__AVR__) || defined(ESP8266)
+    #if SOFTWARE_SERIAL_REQUIRED
       SoftwareSerial* GNSS_Serial; // The serial port of the GNSS module.
     #else
       HardwareSerial* GNSS_Serial; // The serial port of the GNSS module.
     #endif
 
     uint64_t gnssBaud; // The baudrate of the GNSS module.
-    uint64_t debugBaud; // The baudrate of the GNSS module.
+    uint64_t debugBaud; // The baudrate of the debug port.
     bool inited;  // True if the GNSS module serial port is initialized.
     std::vector <NMEA_0183_Data*> dataList;  // List of NMEA data objects.
     int dataCount; // The number of NMEA data objects in the dataList.
@@ -84,17 +91,17 @@ class CSE_GNSS {
     CSE_GNSS (HardwareSerial* gnssSerial, HardwareSerial* debugSerial, uint64_t gnssBaud = 0, uint64_t debugBaud = 0);
 
     // Constructor using one hardware serial port and one software serial port.
-    #if defined(__AVR__) || defined(ESP8266)
+    #if SOFTWARE_SERIAL_REQUIRED
       CSE_GNSS (SoftwareSerial* gnssSerial, uint64_t gnssBaud, HardwareSerial* debugSerial, uint64_t debugBaud);
     #endif
 
-    bool begin();
-    String read (String header = "$GPRMC");
-    String read (int lineCount);
-    int addData (NMEA_0183_Data* data);
-    int getDataCount();
-    NMEA_0183_Data_Ref getDataRef (String name);
-    NMEA_0183_Data_Ref getDataRef (int index);
+    bool begin(); // Initialize the serial ports if necessary.
+    String read (String header = "$GPRMC"); // Read data from the serial port. Specify the start header.
+    String read (int lineCount);  // Read data from the serial port. Specify the number of lines to read.
+    int addData (NMEA_0183_Data* data); // Add an NMEA data object to the dataList.
+    int getDataCount(); // Get the number of NMEA data objects in the dataList.
+    NMEA_0183_Data_Ref getDataRef (String name);  // Get the reference of the NMEA data object.
+    NMEA_0183_Data_Ref getDataRef (int index);  // Get the reference of the NMEA data object.
 };
 
 //======================================================================================//