pre-doxy/clang changes

.github/ISSUE_TEMPLATE.md

@@ -0,0 +1,46 @@
+Thank you for opening an issue on an Adafruit Arduino library repository.  To
+improve the speed of resolution please review the following guidelines and
+common troubleshooting steps below before creating the issue:
+
+- **Do not use GitHub issues for troubleshooting projects and issues.**  Instead use
+  the forums at http://forums.adafruit.com to ask questions and troubleshoot why
+  something isn't working as expected.  In many cases the problem is a common issue
+  that you will more quickly receive help from the forum community.  GitHub issues
+  are meant for known defects in the code.  If you don't know if there is a defect
+  in the code then start with troubleshooting on the forum first.
+
+- **If following a tutorial or guide be sure you didn't miss a step.** Carefully
+  check all of the steps and commands to run have been followed.  Consult the
+  forum if you're unsure or have questions about steps in a guide/tutorial.
+
+- **For Arduino projects check these very common issues to ensure they don't apply**:
+
+  - For uploading sketches or communicating with the board make sure you're using
+    a **USB data cable** and **not** a **USB charge-only cable**.  It is sometimes
+    very hard to tell the difference between a data and charge cable!  Try using the
+    cable with other devices or swapping to another cable to confirm it is not
+    the problem.
+
+  - **Be sure you are supplying adequate power to the board.**  Check the specs of
+    your board and plug in an external power supply.  In many cases just
+    plugging a board into your computer is not enough to power it and other
+    peripherals.
+
+  - **Double check all soldering joints and connections.**  Flakey connections
+    cause many mysterious problems.  See the [guide to excellent soldering](https://learn.adafruit.com/adafruit-guide-excellent-soldering/tools) for examples of good solder joints.
+
+  - **Ensure you are using an official Arduino or Adafruit board.** We can't
+    guarantee a clone board will have the same functionality and work as expected
+    with this code and don't support them.
+
+If you're sure this issue is a defect in the code and checked the steps above
+please fill in the following fields to provide enough troubleshooting information.
+You may delete the guideline and text above to just leave the following details:
+
+- Arduino board:  **INSERT ARDUINO BOARD NAME/TYPE HERE**
+
+- Arduino IDE version (found in Arduino -> About Arduino menu):  **INSERT ARDUINO
+  VERSION HERE**
+
+- List the steps to reproduce the problem below (if possible attach a sketch or
+  copy the sketch code in too): **LIST REPRO STEPS BELOW**

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,26 @@
+Thank you for creating a pull request to contribute to Adafruit's GitHub code!
+Before you open the request please review the following guidelines and tips to
+help it be more easily integrated:
+
+- **Describe the scope of your change--i.e. what the change does and what parts
+  of the code were modified.**  This will help us understand any risks of integrating
+  the code.
+
+- **Describe any known limitations with your change.**  For example if the change
+  doesn't apply to a supported platform of the library please mention it.
+
+- **Please run any tests or examples that can exercise your modified code.**  We
+  strive to not break users of the code and running tests/examples helps with this
+  process.
+
+Thank you again for contributing!  We will try to test and integrate the change
+as soon as we can, but be aware we have many GitHub repositories to manage and
+can't immediately respond to every request.  There is no need to bump or check in
+on a pull request (it will clutter the discussion of the request).
+
+Also don't be worried if the request is closed or not integrated--sometimes the
+priorities of Adafruit's GitHub code (education, ease of use) might not match the
+priorities of the pull request.  Don't fret, the open source community thrives on
+forks and GitHub makes it easy to keep your changes in a forked repo.
+
+After reviewing the guidelines above you can delete this text from the pull request.

.github/workflows/githubci.yml

@@ -0,0 +1,32 @@
+name: Arduino Library CI
+
+on: [pull_request, push, repository_dispatch]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    
+    steps:
+    - uses: actions/setup-python@v4
+      with:
+        python-version: '3.x'
+    - uses: actions/checkout@v3
+    - uses: actions/checkout@v3
+      with:
+         repository: adafruit/ci-arduino
+         path: ci
+
+    - name: Install the prerequisites
+      run: bash ci/actions_install.sh
+
+    - name: Check for correct code formatting with clang-format
+      run: python3 ci/run-clang-format.py -e "ci/*" -e "bin/*" -r .
+
+    - name: Check for correct documentation with doxygen
+      env:
+        GH_REPO_TOKEN: ${{ secrets.GH_REPO_TOKEN }}
+        PRETTYNAME : "Adafruit Bus Ublox Library"
+      run: bash ci/doxy_gen_and_deploy.sh
+
+    - name: Test the code on supported platforms
+      run: python3 ci/build_platform.py main_platforms zero feather32u4

.gitignore

@@ -0,0 +1,4 @@
+# Our handy .gitignore for automation ease
+Doxyfile*
+doxygen_sqlite3.db
+html

Adafruit_UBX.cpp

@@ -13,7 +13,7 @@
  * 
  * @section author Author
  * 
- * Written by Your Name for Project Name.
+ * Written by Limor Fried/Ladyada for Adafruit Industries.
  * 
  * @section license License
  * 

Adafruit_UBX.h

@@ -9,7 +9,7 @@
  * please support Adafruit and open-source hardware by purchasing
  * products from Adafruit!
  *
- * Written by Your Name for Project Name.
+ * Written by Limor Fried/Ladyada for Adafruit Industries.
  * 
  * MIT license, all text here must be included in any redistribution.
  */
@@ -22,7 +22,7 @@
 #include "Adafruit_uBlox_typedef.h"
 
 // UBX protocol constants
-#define UBX_SYNC_CHAR_1 0xB5 // First UBX protocol sync char (µ)
+#define UBX_SYNC_CHAR_1 0xB5 // First UBX protocol sync char (<EFBFBD>)
 #define UBX_SYNC_CHAR_2 0x62 // Second UBX protocol sync char (b)
 // UBX ACK Message IDs
 #define UBX_ACK_NAK 0x00     // Message Not Acknowledged

Adafruit_UBloxDDC.cpp

@@ -17,7 +17,7 @@
  * 
  * @section author Author
  * 
- * Written by Your Name for Project Name.
+ * Written by Limor Fried/Ladyada for Adafruit Industries.
  * 
  * @section license License
  * 

Adafruit_UBloxDDC.h

@@ -10,7 +10,7 @@
  * please support Adafruit and open-source hardware by purchasing
  * products from Adafruit!
  *
- * Written by Your Name for Project Name.
+ * Written by Limor Fried/Ladyada for Adafruit Industries.
  * 
  * MIT license, all text here must be included in any redistribution.
  */

Adafruit_uBlox_Ubx_Messages.h

@@ -0,0 +1,45 @@
+/*!
+ * @file Adafruit_uBlox_Ubx_Messages.h
+ * 
+ * Pre-built UBX message payloads for common tasks
+ * 
+ * Adafruit invests time and resources providing this open source code,
+ * please support Adafruit and open-source hardware by purchasing
+ * products from Adafruit!
+ *
+ * Written by Brent Rubell for Adafruit Industries.
+ * 
+ * MIT license, all text here must be included in any redistribution.
+ */
+
+#ifndef ADAFRUIT_UBLOX_UBX_MESSAGES
+#define ADAFRUIT_UBLOX_UBX_MESSAGES
+
+#include <Arduino.h>
+
+// NMEA Message Configuration Commands (CFG-MSG)
+// Format: {msgClass, msgID, rate_I2C, rate_UART1, rate_UART2, rate_USB, rate_SPI, reserved}
+
+// Enable specific NMEA message sentences to output on the DDC interface
+static uint8_t UBX_CFG_MSG_NMEA_GGA_ENABLE[]  = {0xF0, 0x00, 0x01, 0x00, 0x00, 0x00, 0x00, 0x00};
+static uint8_t UBX_CFG_MSG_NMEA_GLL_ENABLE[] = {0xF0, 0x01, 0x01, 0x00, 0x00, 0x00, 0x00, 0x00};
+static uint8_t UBX_CFG_MSG_NMEA_GSA_ENABLE[] = {0xF0, 0x02, 0x01, 0x00, 0x00, 0x00, 0x00, 0x00};
+static uint8_t UBX_CFG_MSG_NMEA_GSV_ENABLE[] = {0xF0, 0x03, 0x01, 0x00, 0x00, 0x00, 0x00, 0x00};
+static uint8_t UBX_CFG_MSG_NMEA_RMC_ENABLE[]  = {0xF0, 0x04, 0x01, 0x00, 0x00, 0x00, 0x00, 0x00};
+static uint8_t UBX_CFG_MSG_NMEA_VTG_ENABLE[] = {0xF0, 0x05, 0x01, 0x00, 0x00, 0x00, 0x00, 0x00};
+// Disable specific NMEA message sentences from outputting on the DDC interface
+static uint8_t UBX_CFG_MSG_NMEA_GGA_DISABLE[]  = {0xF0, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00};
+static uint8_t UBX_CFG_MSG_NMEA_GLL_DISABLE[] = {0xF0, 0x01, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00};
+static uint8_t UBX_CFG_MSG_NMEA_GSA_DISABLE[] = {0xF0, 0x02, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00};
+static uint8_t UBX_CFG_MSG_NMEA_GSV_DISABLE[] = {0xF0, 0x03, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00};
+static uint8_t UBX_CFG_MSG_NMEA_RMC_DISABLE[]  = {0xF0, 0x04, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00};
+static uint8_t UBX_CFG_MSG_NMEA_VTG_DISABLE[] = {0xF0, 0x05, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00};
+
+// Navigation Rate Configuration Commands (CFG-RATE)
+// Format: {measRate_ms (2 bytes), navRate, timeRef}
+static uint8_t UBX_CFG_RATE_1HZ[]  = {0xE8, 0x03, 0x01, 0x00, 0x01, 0x00};
+static uint8_t UBX_CFG_RATE_2HZ[]  = {0xF4, 0x01, 0x01, 0x00, 0x01, 0x00}; 
+static uint8_t UBX_CFG_RATE_5HZ[]  = {0xC8, 0x00, 0x01, 0x00, 0x01, 0x00};
+static uint8_t UBX_CFG_RATE_10HZ[] = {0x64, 0x00, 0x01, 0x00, 0x01, 0x00};
+
+#endif // ADAFRUIT_UBLOX_UBX_MESSAGES

Adafruit_uBlox_typedef.h

@@ -7,7 +7,7 @@
  * please support Adafruit and open-source hardware by purchasing
  * products from Adafruit!
  *
- * Written by Your Name for Project Name.
+ * Written by Limor Fried/Ladyada for Adafruit Industries.
  * 
  * MIT license, all text here must be included in any redistribution.
  */

LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2017 Adafruit Industries
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,13 @@
+# Adafruit uBlox Library [![Build Status](https://github.com/adafruit/Adafruit_uBlox/workflows/Arduino%20Library%20CI/badge.svg)](https://github.com/adafruit/Adafruit_uBlox/actions)
+
+This is a driver library to abstract away the details of communicating with u-blox GPS and RTK modules. It provides a simple interface for sending and receiving data over a generic Stream interface.
+
+This library provides two main classes:
+- `Adafruit_UBX`: Interfaces with u-blox GPS/RTK modules using any stream object as an input (UART, DDC, or other) and parses UBX protocol messages.
+- `Adafruit_UBloxDDC`: Interface for communicating with u-blox modules over DDC (I2C).
+
+For parsing NMEA sentences, we provide an example for using this library with the [Adafruit_GPS library](https://github.com/adafruit/Adafruit_GPS).
+
+Adafruit invests time and resources providing this open source code, please support Adafruit and open-source hardware by purchasing products from Adafruit!
+
+MIT license, all text above must be included in any redistribution

examples/ublox_dcc.ino

@@ -0,0 +1,63 @@
+/*!
+ * @file ublox_ddc_example.ino
+ * 
+ * Example sketch demonstrating the use of the Adafruit_UBloxDDC library
+ * with u-blox GPS/RTK modules over I2C (DDC) interface.
+ * 
+ * This example simply streams all raw bytes from the GPS module to the
+ * Serial port so you can see the NMEA sentences in their original format.
+ * 
+ * Written by Ladyada for Adafruit Industries.
+ * 
+ * MIT license, all text above must be included in any redistribution
+ */
+
+#include "Adafruit_UBloxDDC.h"
+
+// Create Adafruit_UBloxDDC object with default I2C address (0x42)
+Adafruit_UBloxDDC gps;
+
+// Buffer for reading chunks of data
+const size_t BUFFER_SIZE = 64;
+uint8_t buffer[BUFFER_SIZE];
+
+void setup() {
+  // Initialize serial port for debugging
+  Serial.begin(115200);
+  while (!Serial) {
+    ; // Wait for serial port to connect
+  }
+  
+  Serial.println("Adafruit UBlox DDC Raw NMEA Stream Example");
+  
+  // Initialize GPS module
+  if (gps.begin()) {
+    Serial.println("GPS module found!");
+  } else {
+    Serial.println("Failed to connect to GPS module!");
+    while (1); // Don't proceed if we couldn't connect to the module
+  }
+  
+  Serial.println("Streaming raw data from GPS module...");
+  Serial.println("------------------------------------");
+}
+
+void loop() {
+  // Check how many bytes are available
+  int bytesAvailable = gps.available();
+  
+  if (bytesAvailable > 0) {
+    // Read up to BUFFER_SIZE bytes at a time
+    size_t bytesToRead = min(bytesAvailable, (int)BUFFER_SIZE);
+    size_t bytesRead = gps.readBytes(buffer, bytesToRead);
+    
+    // Stream the bytes directly to Serial
+    // This will show raw NMEA sentences
+    for (size_t i = 0; i < bytesRead; i++) {
+      Serial.write(buffer[i]);
+    }
+  }
+  
+  // Short delay to prevent overwhelming the serial monitor
+  delay(10);
+}

examples/ublox_ubxtest.ino

@@ -0,0 +1,151 @@
+/*!
+ * @file ubx_mode_test.ino
+ * 
+ * Test sketch to verify switching to UBX protocol mode
+ * This example uses I2C (DDC) to communicate with a u-blox module.
+ * 
+ * Written by Ladyada for Adafruit Industries.
+ * 
+ * MIT license, all text above must be included in any redistribution
+ */
+
+#include "Adafruit_UBloxDDC.h"
+#include "Adafruit_UBX.h"
+#include "Adafruit_uBlox_typedef.h"
+
+// Create Adafruit_UBloxDDC object with default I2C address (0x42)
+Adafruit_UBloxDDC ddc;
+
+// Create Adafruit_UBX parser using the DDC object as input stream
+Adafruit_UBX ubx(ddc);
+
+// Variables to track message statistics
+uint32_t messageCount = 0;
+uint32_t lastMsgTime = 0;
+bool ubxModeConfirmed = false;
+
+// Callback function for UBX messages
+void ubxMessageCallback(uint8_t msgClass, uint8_t msgId, uint16_t payloadLen, uint8_t *payload) {
+  messageCount++;
+  lastMsgTime = millis();
+  
+  // First successful UBX message confirms we're in UBX mode
+  if (!ubxModeConfirmed) {
+    ubxModeConfirmed = true;
+    Serial.println("SUCCESS: UBX mode confirmed! Receiving UBX messages.");
+  }
+  
+  // Print message details
+  Serial.print("UBX Message: Class 0x");
+  if (msgClass < 0x10) Serial.print("0");
+  Serial.print(msgClass, HEX);
+  
+  Serial.print(", ID 0x");
+  if (msgId < 0x10) Serial.print("0");
+  Serial.print(msgId, HEX);
+  
+  Serial.print(", Length: ");
+  Serial.print(payloadLen);
+  Serial.println(" bytes");
+}
+
+void setup() {
+  // Initialize serial port for debugging
+  Serial.begin(115200);
+  while (!Serial) {
+    ; // Wait for serial port to connect
+  }
+  
+  Serial.println("\n\n------------- UBX Mode Test -------------");
+  Serial.println("This test will try to switch a u-blox module to UBX protocol");
+  
+  // Initialize GPS module
+  Serial.print("Connecting to u-blox module via I2C...");
+  if (ddc.begin()) {
+    Serial.println(" SUCCESS!");
+  } else {
+    Serial.println(" FAILED!");
+    Serial.println("Check connections and try again.");
+    while (1); // Don't proceed if we couldn't connect to the module
+  }
+  
+  // Show current data format (should be NMEA)
+  Serial.println("\nCurrent data format (should be NMEA sentences):");
+  Serial.println("------------------------------------------------");
+  
+  // Show some raw data
+  unsigned long startTime = millis();
+  while (millis() - startTime < 3000) {
+    if (ddc.available()) {
+      int c = ddc.read();
+      if (c != -1) {
+        Serial.write(c);
+      }
+    }
+  }
+  
+  Serial.println("\n------------------------------------------------");
+  
+  // Initialize UBX parser and set debug mode
+  ubx.begin();
+  ubx.verbose_debug = 2;  // Enable basic debug output
+  
+  // Set the callback function for UBX messages
+  ubx.setMessageCallback(ubxMessageCallback);
+  
+  // Now switch to UBX mode
+  Serial.println("\nSwitching to UBX-only mode on DDC port...");
+  
+  UBXSendStatus status = ubx.setUBXOnly(UBX_PORT_DDC, true, 1000);
+  
+  switch (status) {
+    case UBX_SEND_SUCCESS:
+      Serial.println("SUCCESS: UBX configuration command acknowledged!");
+      break;
+    case UBX_SEND_NAK:
+      Serial.println("ERROR: UBX configuration command was rejected by the module.");
+      break;
+    case UBX_SEND_FAIL:
+      Serial.println("ERROR: Failed to send UBX configuration command.");
+      break;
+    case UBX_SEND_TIMEOUT:
+      Serial.println("ERROR: Timeout waiting for acknowledgment.");
+      break;
+  }
+  
+  if (status != UBX_SEND_SUCCESS) {
+    Serial.println("Continuing anyway to see if we receive any UBX messages...");
+  }
+  
+  Serial.println("\nWaiting for UBX messages (timeout: 5 seconds)...");
+  lastMsgTime = millis();
+}
+
+void loop() {
+  // Check for UBX messages
+  ubx.checkMessages();
+  
+  // Display statistics every second
+  static uint32_t lastStatsTime = 0;
+  if (millis() - lastStatsTime >= 1000) {
+    lastStatsTime = millis();
+    Serial.print("Status: Messages received: ");
+    Serial.print(messageCount);
+    
+    // Check for timeout
+    if (!ubxModeConfirmed && (millis() - lastMsgTime > 5000)) {
+      Serial.println("\n\nTIMEOUT: No UBX messages received within 5 seconds.");
+      Serial.println("Possible issues:");
+      Serial.println("1. Module doesn't support UBX protocol on this port");
+      Serial.println("2. Configuration command wasn't received properly");
+      Serial.println("3. Module requires different configuration");
+      Serial.println("\nTry using verbose_debug = 2 for more details.");
+      while(1); // Stop execution
+    }
+    
+    Serial.println();
+  }
+  
+  // Short delay to prevent overwhelming the processor
+  delay(10);
+}

library.properties

@@ -0,0 +1,10 @@
+name=Adafruit uBlox
+version=1.0.0
+author=Adafruit
+maintainer=Adafruit <info@adafruit.com>
+sentence=Library for interfacing with u-blox GPS/RTK modules.
+paragraph=Library for interfacing with u-blox GPS/RTK modules.
+category=Communication
+url=https://github.com/adafruit/Adafruit_uBlox/
+architectures=*
+depends=Adafruit BusIO