diff --git a/.github/ISSUE_TEMPLATE.md b/.github/ISSUE_TEMPLATE.md new file mode 100644 index 0000000..cc6d283 --- /dev/null +++ b/.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** \ No newline at end of file diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 0000000..a110620 --- /dev/null +++ b/.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. \ No newline at end of file diff --git a/.github/workflows/githubci.yml b/.github/workflows/githubci.yml new file mode 100644 index 0000000..2ec068d --- /dev/null +++ b/.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 \ No newline at end of file diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..1daef4a --- /dev/null +++ b/.gitignore @@ -0,0 +1,4 @@ +# Our handy .gitignore for automation ease +Doxyfile* +doxygen_sqlite3.db +html \ No newline at end of file diff --git a/Adafruit_UBX.cpp b/Adafruit_UBX.cpp index c0b7b6b..49d1be8 100644 --- a/Adafruit_UBX.cpp +++ b/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 * diff --git a/Adafruit_UBX.h b/Adafruit_UBX.h index 6691e12..e7f34b9 100644 --- a/Adafruit_UBX.h +++ b/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 (�) #define UBX_SYNC_CHAR_2 0x62 // Second UBX protocol sync char (b) // UBX ACK Message IDs #define UBX_ACK_NAK 0x00 // Message Not Acknowledged diff --git a/Adafruit_UBloxDDC.cpp b/Adafruit_UBloxDDC.cpp index b4c8e95..e01f132 100644 --- a/Adafruit_UBloxDDC.cpp +++ b/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 * diff --git a/Adafruit_UBloxDDC.h b/Adafruit_UBloxDDC.h index b5138db..9067ffd 100644 --- a/Adafruit_UBloxDDC.h +++ b/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. */ diff --git a/Adafruit_uBlox_Ubx_Messages.h b/Adafruit_uBlox_Ubx_Messages.h new file mode 100644 index 0000000..51663a6 --- /dev/null +++ b/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 + +// 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 \ No newline at end of file diff --git a/Adafruit_uBlox_typedef.h b/Adafruit_uBlox_typedef.h index f8e44b2..2005019 100644 --- a/Adafruit_uBlox_typedef.h +++ b/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. */ diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..860e3e2 --- /dev/null +++ b/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. \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..8ca8732 --- /dev/null +++ b/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 \ No newline at end of file diff --git a/examples/ublox_dcc.ino b/examples/ublox_dcc.ino new file mode 100644 index 0000000..9ff22a7 --- /dev/null +++ b/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); +} diff --git a/examples/ublox_ubxtest.ino b/examples/ublox_ubxtest.ino new file mode 100644 index 0000000..fd87a1d --- /dev/null +++ b/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); +} diff --git a/library.properties b/library.properties new file mode 100644 index 0000000..520d918 --- /dev/null +++ b/library.properties @@ -0,0 +1,10 @@ +name=Adafruit uBlox +version=1.0.0 +author=Adafruit +maintainer=Adafruit +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 \ No newline at end of file