Published December 21, 2025 © GPL3+

Getting Started with Ai-Thinker GP-02: BDS/GPS/GNSS

Discover how to set up the Ai‑Thinker GP‑02 module with multiple ESP32 variants and an OLED display.

BeginnerProtip1 hour522

Getting Started with Ai-Thinker GP-02: BDS/GPS/GNSS

Things used in this project

Hardware components

DFRobot FireBeetle 2 Board ESP32-S3 (N16R8) AIoT Microcontroller with Camera

Seeed Studio XIAO ESP32S3 Sense

Seeed Studio XIAO ESP32C3

ESP32 DEV KIT V1

Ai-Thinker GP-02 BDS/GPS/GNSS Module

OLED Display

Breadboard

Jumper Cables

Software apps and online services

Arduino IDE

Story

🚀 Introduction

There aren’t much content or beginner‑friendly tutorials available for the Ai-Thinker GP‑02 GNSSModule, even though it’s a compact and powerful receiver built around the AT6558R chip with a built‑in ceramic antenna. This guide aims to fill that gap by walking you step‑by‑step through how to connect and use the GP‑02 with a wide range of popular microcontrollers.

We’ll cover:

Seeed Studio XIAO ESP32S3
Seeed Studio XIAO ESP32C3
DFRobot FireBeetle 2 ESP32S3
ESP32 DEV KIT V1 (the most widely available ESP32 variant)

For each microcontroller, this guide provides:

Proper pinouts for connecting the GP‑02 via UART.
Example code snippets using the TinyGPSPlus library.
Explanations of how the module receives satellite signals, parses them into NMEA sentences, and how the microcontroller reads and processes that data.

By the end, you’ll have a clear understanding of how to integrate the GP‑02 into your IoT or embedded projects, regardless of which ESP32 board you’re using.

📦 Device Overview

The Ai-Thinker GP‑02 is a high‑performance BDS/GPS/GNSS multi‑mode satellite navigation receiver SoC module. It integrates:

RF front‑end for capturing weak satellite signals.
Digital baseband processor for demodulation and decoding.
32‑bit RISC CPU for positioning algorithms.
Power management for efficient operation.
Active antenna detection and protection for reliability.
Built‑in ceramic antenna for compact design and simplified deployment.

It supports multiple satellite navigation systems:

BDS (BeiDou) – China
GPS – United States
GLONASS – Russia

GNSS

This multi‑system joint positioning improves accuracy and robustness.The GP‑02 communicates using the industry‑standard NMEA protocol, outputting data such as latitude, longitude, altitude, speed, and satellite information in simple ASCII text sentences (e.g., $GPRMC, $GPGGA). Because NMEA is universally supported, the module can be connected to any microcontroller via a UART interface (TX/RX pins).

Satellites orbit Earth and broadcast signals in the L‑band.
Each signal contains: precise timing information, orbital data (ephemeris), and satellite ID codes.
The receiver measures the time delay to calculate distance.
With signals from at least 4 satellites, the module computes latitude, longitude, altitude, and clock offset.

⚙️ GP‑02 Module Internals

Signal Reception: RF front‑end amplifies and filters satellite signals.
Baseband Processing: Correlates signals with satellite codes, extracts navigation data.
CPU Computation: Runs trilateration algorithms to determine position.
Output: Provides standard NMEA sentences (e.g., $GPRMC, $GPGGA) via UART.

🔌 Microcontroller Communication (TX/RX)

The GP‑02 communicates with microcontrollers (ESP32, Arduino) via UART serial.

TX (Transmit): GP‑02 sends NMEA sentences containing GPS data.
RX (Receive): GP‑02 listens to the microcontroller, which can send configuration commands back to the module.

The microcontroller reads the data stream from the GP‑02 and parses it using libraries such as TinyGPSPlus.

🛠️ Prerequisites

Hardware

GP‑02 module

If you are from India, you can purchase the GP‑02 GNSS module from below websites:

Ai-Thinker GP-02 Precision GPS/GNSS Module - techiesms

Ai-Thinker GP-02 Kit GPS Development Board BDS/GNSS/GPS Module – REES52

One of the supported microcontrollers:

Seeed Studio XIAO ESP32S3

Seeed Studio XIAO ESP32C3

DFRobot FireBeetle 2 ESP32S3

ESP32 DEV KIT V1

OLED display (SSD1306 or SH1106, I²C interface)
Jumper wires and breadboard

Software

Arduino IDE (latest version)
ESP32 board support installed via Arduino Boards Manager

Libraries:

TinyGPSPlus (for parsing NMEA sentences)
Adafruit SSD1306 (for OLED Display)

📚 Installing the Required Libraries

In the Arduino IDE, navigate to Library Manager window and install the following libraries:

TinyGPSPlus

Install the latest version available

Adafruit SSD1306

1 / 2 • Install the latest version available

📐 Circuit Diagrams

Using the images below, connect your microcontroller (MCU) with the GP‑02 module and the OLED display using jumper wires.

1 / 4 • Pin numbers are detailed in the following text

1. Seeed Studio XIAO ESP32S3

GNSS module TX → XIAO RX D7
GNSS module RX → XIAO TX D6
GNSS module VCC → 5V
GNSS module GND → GND
OLED SDA → XIAO SDA
OLED SCL → XIAO SCL
OLED VCC → 5V
OLED GND → GND

2. Seeed Studio XIAO ESP32C3

GNSS module TX → XIAO RX D7
GNSS module RX → XIAO TX D6
GNSS module VCC → 5V
GNSS module GND → GND
OLED SDA → XIAO SDA
OLED SCL → XIAO SCL
OLED VCC → 5V
OLED GND → GND

3. DFRobot FireBeetle 2 ESP32S3

GNSS module TX → FireBeetle RX GPIO44
GNSS module RX → FireBeetle TX GPIO43
GNSS module VCC → 5v
GNSS module GND → GND
OLED SDA → FireBeetle SDA
OLED SCL → FireBeetle SCL
OLED VCC → 5V
OLED GND → GND

4. ESP32 DEV KIT V1

GNSS module TX → ESP32 RX GPIO16
GNSS module RX → ESP32 TX GPIO17
GNSS module VCC → 5v
GNSS module GND → GND
OLED SDA → ESP32 GPIO21 (default SDA)
OLED SCL → ESP32 GPIO22 (default SCL)
OLED VCC → 5V
OLED GND → GND

💻 Uploading the Code

Each board has its own method of uploading code, so make sure to pay close attention to the instructions specific to your microcontroller. The upload process may vary slightly depending on the board drivers, USB connection, or IDE settings.

Note: Before we begin uploading the main code, connect only the OLED display to your microcontroller (do not connect the GNSS module yet). Run the WireScan sketch provided below — this will detect the I²C address of your OLED display.

My OLED address is 0x3C.
Please update the I²C address in the upcoming microcontroller codes according to the value you find.

#include "Wire.h"

void setup() {
    Serial.begin(115200);
    Wire.begin();
}
void loop() {
    byte error, address;
    int nDevices = 0;
    delay(5000);

    Serial.println("Scanning for I2C devices ...");
    for (address = 0x01; address < 0x7f; address++) {
        Wire.beginTransmission(address);
        error = Wire.endTransmission();
        if (error == 0) {
            Serial.printf("I2C device found at address 0x%02X\n", address);
            nDevices++;
        } else if (error != 2) {
          Serial.printf("Error %d at address 0x%02X\n", error, address);
        }
    }
    if (nDevices == 0) {
        Serial.println("No I2C devices found");
    }
}

Whether you are running the WireScan sketch or the upcoming GNSS code, always follow the Arduino IDE upload instructions shown in the image for your specific board.

1. Seeed Studio XIAO ESP32S3

Follow the instructions from the images below:

1 / 8 • Click along with the arrow

2. Seeed Studio XIAO ESP32C3

Follow the same steps as for the Seeed Studio XIAO ESP32S3, but be sure to select the correct board as shown in the image. Also, don’t forget to choose the right COM port in the Arduino IDE (Tools → Port) that matches your connected board. All other settings remain unchanged.

Type "XIAO ESP32 C3", select the board, click on "OK"

3. DFRobot FireBeetle 2 ESP32S3

Follow the instructions from the images below:

1 / 9 • Click along with the arrow

4. ESP32 DEV KIT V1

Type "ESP32 Dev Module", select the board, click on "OK"

📲 Flashing GP‑02 Module Codes

Now that we’ve gone through the step‑by‑step images showing how to upload code using the Arduino IDE, it’s time to move on to the individual microcontroller codes for the GP‑02 module.

Please refer back to the images for the correct upload instructions (board selection, port number, and upload method) when flashing the codes into your respective microcontroller. The process remains the same — only the code changes depending on the board you are using.

👉 The complete codes for each individual board have been attached below this guide in the Code section.

💡 Important Note (Line 11 of the code)

#define ADDRESS 0x3C   // Replace this with the I2C address of your OLED display

Please replace 0x3C with the I2C address obtained from the WireScan sketch (shown earlier in the Serial Monitor). This ensures the code communicates correctly with your specific OLED display!

📡 Positioning the Ceramic Antenna

For reliable GPS/GNSS reception, the ceramic antenna must face the sky.(It can work indoors as well, but signals are weaker and the fix takes more time compared to outdoors testing. For best results, test outdoors first.)

I live in an apartment building with 5 floors overall, and even indoors I was able to get a fix when I placed the setup near a window.

📷 I am attaching the image below to illustrate the setup.

1 / 2 • Ceramic antenna facing sky

📷 Guide Illustration: GNSS Module with Boards

🖥️ OLED Display Status Messages

When running the code, the OLED will show different messages depending on whether the GPS module is detected:

“Waiting for GPS” → The system is powered and waiting to receive valid serial data from the GNSS module.
“No GPS detected!” (after ~5 seconds) → No valid data was received.

🔧 Troubleshooting

If you see “No GPS detected!”, first recheck the wiring connections between your microcontroller and the GNSS module.
If wiring is correct and the error persists, it likely means the GPS module is damaged or not functioning properly.

📷 I am attaching the images below to illustrate both display states.

1 / 2 • OLED when powered ON

🖥️ OLED When GNSS Module is Working

Once the GNSS module begins receiving valid satellite data, the OLED display will start showing:

Latitude(initially invalid during cold or hot start)
Longitude(initially invalid during cold or hot start)
Number of satellites connected(shows 0 until a fix is achieved)
Altitude(shows 0 until a fix is achieved)
Speed(shows 0 until movement is detected after a fix)
Course (shows 0 until movement is detected after a fix)
UTC Time
Date

⚠️ Important Notes:

During a cold start (first power‑on), UTC time and date might appear incorrect until a proper fix is achieved.
During a hot start (resume after recent satellite lock):(faster reacquisition since satellite data is already cached) — even if latitude, longitude, satellites, altitude, speed, or course are not yet available, the date and UTC time are cached and will display correctly.

📷 I am attaching the image below.

Initially during cold/hot start

🛰️ OLED When Satellite Lock/Fix

Once the GNSS module achieves a satellite lock (fix), the OLED display will update with valid positioning data:

Latitude & Longitude → Now correctly received and displayed.
Number of Satellites → Updated from 0 to the actual count of satellites connected.
Altitude → Updated from 0 to the measured altitude.
Speed → Updated from 0 to the current movement speed.
Course (direction of movement) → Updated from 0 to the actual course.
UTC Time → Corrected if previously wrong during cold start.
Date → Corrected if previously wrong during cold start.

⚡ Key Point:After satellite lock, all values that were previously invalid or showing as 0 will be updated with real data. This is the stage where your GNSS module confirms it is working properly.

📷 I am attaching the image below.

During Satellite Lock/Fix

🎮 Microcontroller Setups (Image Reference)

1 / 4 • Seeed Studio XIAO ESP32S3

📑 GP‑02 GNSS Module Technical Details

From the datasheet, here are the key performance parameters of the Ai‑Thinker GP‑02 GNSS module:

Performance Parameters

Cold Start vs Hot Start: Cold start means the module has no prior satellite data; hot start uses cached data, hence much faster.
Accuracy: <2 m positioning accuracy is sufficient for most IoT and navigation projects.
Update Rate: Default is 1 Hz, but can be configured up to 5 Hz for faster tracking.
Timing Accuracy: <30 ns makes it suitable for synchronization tasks in communication systems.

✅ Conclusion

In this guide, we explored the GP‑02 GNSS module integration with multiple microcontrollers, step‑by‑step upload instructions, OLED display behaviour, antenna positioning, and troubleshooting methods.

🌍 Real‑World Performance

Although the datasheet specifies typical cold start and hot start timings, in practice I observed:

Cold Start: ~40 seconds
Hot Start: ~7 seconds

These timings can vary depending on factors such as:

Location and surrounding environment (urban vs open sky)
Weather conditions
Satellite positioning and visibility
Antenna placement and orientation
Electromagnetic interference nearby

Despite these variations, the module consistently delivers:

Positioning accuracy of less than 2 m, as claimed in the datasheet — locations are shown perfectly.
Speed readings that are highly accurate and precise.

📌 Final Note

The more satellites the module connects to, the better and more reliable the data received — ensuring improved accuracy for position, speed, and timing.

Code

// Include libraries for GPS parsing, I2C communication, graphics, and OLED display
#include <TinyGPSPlus.h>
#include <Wire.h>                    // I2C communication library
#include <Adafruit_GFX.h>            // Graphics library for OLED
#include <Adafruit_SSD1306.h>        // SSD1306 OLED display driver

// OLED display dimensions (128x64 pixels standard)
#define SCREEN_WIDTH 128    // OLED screen width in pixels
#define SCREEN_HEIGHT 64    // OLED screen height in pixels
#define ADDRESS 0x3C        // Replace this with the I2C address of your OLED display

// OLED reset pin configuration (-1 means use Arduino reset pin)
#define OLED_RESET -1                   // No dedicated reset pin, share Arduino reset

// Create OLED display object with specified dimensions, I2C interface, and reset pin
Adafruit_SSD1306 display(SCREEN_WIDTH, SCREEN_HEIGHT, &Wire, OLED_RESET);

// Create GPS parser object
TinyGPSPlus gps;                    // TinyGPSPlus object for NMEA sentence parsing

// Define GPS serial port and pin assignments for XIAO ESP32S3/XIAO ESP32C3
#define gpsSerial Serial1               // Use hardware Serial1 (UART1) for GPS
#define RX_PIN D7                       // XIAO D7 (RX pin)  GPS TX
#define TX_PIN D6                       // XIAO D6 (TX pin)  GPS RX (optional)

// Setup function - runs once at startup
void setup() {
  // Initialize GPS serial port on Serial1 with specified pins and GPS baud rate (9600)
  gpsSerial.begin(9600, SERIAL_8N1, RX_PIN, TX_PIN);  // 8 data bits, no parity, 1 stop bit

  // Initialize OLED display with internal power supply and I2C address
  if (!display.begin(SSD1306_SWITCHCAPVCC, ADDRESS)) {   // Try to start OLED at I2C address 
    Serial.println(F("SSD1306 allocation failed"));      // Print error if OLED fails
    for (;;);                                            // Infinite loop if OLED fails
  }
  
  // Clear OLED display buffer
  display.clearDisplay();
  
  // Configure OLED text rendering settings
  display.setTextSize(1);           // Set text size to 1 (smallest)
  display.setTextColor(SSD1306_WHITE);  // Set text color to white
  display.setCursor(0, 0);          // Set text cursor to top-left corner (x=0, y=0)
  
  // Display startup message on OLED
  display.println("Waiting for GPS...");
  display.display();                // Update OLED with buffer contents
}

// Main loop - runs continuously
void loop() {
  // Read all available GPS data from serial port
  while (gpsSerial.available() > 0) {
    // Read one byte from GPS serial port
    if (gps.encode(gpsSerial.read())) {     // Parse NMEA data, returns true if valid
      displayLocationInfo();                // Update display with GPS data when valid fix
    }
  }

  // Check if 5 seconds passed with no GPS data (less than 10 chars processed)
  if (millis() > 5000 && gps.charsProcessed() < 10) {
    display.clearDisplay();                 // Clear OLED buffer
    display.setCursor(0, 0);                // Reset cursor to top-left
    display.println("No GPS detected!");    // Show error message
    display.display();                      // Update OLED display
    while (true);                           // Stop program execution
  }
}

// Function to display GPS location information on OLED
void displayLocationInfo() {
  display.clearDisplay();                   // Clear previous display content
  display.setCursor(0, 0);                  // Reset cursor to top-left corner

  // Display Latitude
  display.print("Lat: ");                   // Print "Lat: " label
  if (gps.location.isValid()) {             // Check if latitude data is valid
    display.println(gps.location.lat(), 6); // Print latitude with 6 decimal places
  } else {
    display.println("Invalid");             // Show "Invalid" if no valid fix
  }

  // Display Longitude
  display.print("Lng: ");                   // Print "Lng: " label
  if (gps.location.isValid()) {             // Check if longitude data is valid
    display.println(gps.location.lng(), 6); // Print longitude with 6 decimal places
  } else {
    display.println("Invalid");             // Show "Invalid" if no valid fix
  }

  // Display number of satellites
  display.print("Sats: ");                  // Print "Sats: " label
  display.println(gps.satellites.value());  // Print satellite count

  // Display altitude
  display.print("Alt: ");                   // Print "Alt: " label
  display.print(gps.altitude.meters());     // Print altitude in meters
  display.println(" m");                    // Print units

  // Display ground speed
  display.print("Spd: ");                   // Print "Spd: " label
  display.print(gps.speed.kmph());          // Print speed in km/h
  display.println(" km/h");                 // Print units

  // Display course / direction of movement
  display.print("Course: ");                // Print "Course: " label
  display.print(gps.course.deg());          // Print couse in degrees
  display.write(247);                       // Print units
  display.println();                     

  // Display UTC time
  display.print("UTC: ");                   // Print "UTC: " label
  if (gps.time.isValid()) {                 // Check if time data is valid
    // Format time as HH:MM:SS using printf-style formatting
    display.printf("%02d:%02d:%02d\n",
                   gps.time.hour(),
                   gps.time.minute(),
                   gps.time.second());
  } else {
    display.println("Invalid");             // Show "Invalid" if no time fix
  }

  // Display current date
  display.print("Date: ");                   // Print "Date: " label
  if (gps.date.isValid()) {                  // Check if date data is valid
    // Format date as DAY/MONTH/YEAR using printf-style formatting
    display.printf("%02d/%02d/%04d\n",
                  gps.date.day(),
                  gps.date.month(),
                  gps.date.year());
  } else {
    display.println("Invalid");               // Show "Invalid" if no time fix
  }
  display.display();                        // Push buffer to OLED screen (refresh display)
}

// Include libraries for GPS parsing, I2C communication, graphics, and OLED display
#include <TinyGPSPlus.h>
#include <Wire.h>                    // I2C communication library
#include <Adafruit_GFX.h>            // Graphics library for OLED
#include <Adafruit_SSD1306.h>        // SSD1306 OLED display driver

// OLED display dimensions (128x64 pixels standard)
#define SCREEN_WIDTH 128    // OLED screen width in pixels
#define SCREEN_HEIGHT 64    // OLED screen height in pixels
#define ADDRESS 0x3C        // Replace this with the I2C address of your OLED display

// OLED reset pin configuration (-1 means use Arduino reset pin)
#define OLED_RESET -1                   // No dedicated reset pin, share Arduino reset

// Create OLED display object with specified dimensions, I2C interface, and reset pin
Adafruit_SSD1306 display(SCREEN_WIDTH, SCREEN_HEIGHT, &Wire, OLED_RESET);

// Create GPS parser object
TinyGPSPlus gps;                    // TinyGPSPlus object for NMEA sentence parsing

// Define GPS serial port and pin assignments for XIAO ESP32S3/XIAO ESP32C3
#define gpsSerial Serial1               // Use hardware Serial1 (UART1) for GPS
#define RX_PIN D7                       // XIAO D7 (RX pin)  GPS TX
#define TX_PIN D6                       // XIAO D6 (TX pin)  GPS RX (optional)

// Setup function - runs once at startup
void setup() {
  // Initialize GPS serial port on Serial1 with specified pins and GPS baud rate (9600)
  gpsSerial.begin(9600, SERIAL_8N1, RX_PIN, TX_PIN);  // 8 data bits, no parity, 1 stop bit

  // Initialize OLED display with internal power supply and I2C address
  if (!display.begin(SSD1306_SWITCHCAPVCC, ADDRESS)) {   // Try to start OLED at I2C address 
    Serial.println(F("SSD1306 allocation failed"));      // Print error if OLED fails
    for (;;);                                            // Infinite loop if OLED fails
  }
  
  // Clear OLED display buffer
  display.clearDisplay();
  
  // Configure OLED text rendering settings
  display.setTextSize(1);           // Set text size to 1 (smallest)
  display.setTextColor(SSD1306_WHITE);  // Set text color to white
  display.setCursor(0, 0);          // Set text cursor to top-left corner (x=0, y=0)
  
  // Display startup message on OLED
  display.println("Waiting for GPS...");
  display.display();                // Update OLED with buffer contents
}

// Main loop - runs continuously
void loop() {
  // Read all available GPS data from serial port
  while (gpsSerial.available() > 0) {
    // Read one byte from GPS serial port
    if (gps.encode(gpsSerial.read())) {     // Parse NMEA data, returns true if valid
      displayLocationInfo();                // Update display with GPS data when valid fix
    }
  }

  // Check if 5 seconds passed with no GPS data (less than 10 chars processed)
  if (millis() > 5000 && gps.charsProcessed() < 10) {
    display.clearDisplay();                 // Clear OLED buffer
    display.setCursor(0, 0);                // Reset cursor to top-left
    display.println("No GPS detected!");    // Show error message
    display.display();                      // Update OLED display
    while (true);                           // Stop program execution
  }
}

// Function to display GPS location information on OLED
void displayLocationInfo() {
  display.clearDisplay();                   // Clear previous display content
  display.setCursor(0, 0);                  // Reset cursor to top-left corner

  // Display Latitude
  display.print("Lat: ");                   // Print "Lat: " label
  if (gps.location.isValid()) {             // Check if latitude data is valid
    display.println(gps.location.lat(), 6); // Print latitude with 6 decimal places
  } else {
    display.println("Invalid");             // Show "Invalid" if no valid fix
  }

  // Display Longitude
  display.print("Lng: ");                   // Print "Lng: " label
  if (gps.location.isValid()) {             // Check if longitude data is valid
    display.println(gps.location.lng(), 6); // Print longitude with 6 decimal places
  } else {
    display.println("Invalid");             // Show "Invalid" if no valid fix
  }

  // Display number of satellites
  display.print("Sats: ");                  // Print "Sats: " label
  display.println(gps.satellites.value());  // Print satellite count

  // Display altitude
  display.print("Alt: ");                   // Print "Alt: " label
  display.print(gps.altitude.meters());     // Print altitude in meters
  display.println(" m");                    // Print units

  // Display ground speed
  display.print("Spd: ");                   // Print "Spd: " label
  display.print(gps.speed.kmph());          // Print speed in km/h
  display.println(" km/h");                 // Print units

  // Display course / direction of movement
  display.print("Course: ");                // Print "Course: " label
  display.print(gps.course.deg());          // Print couse in degrees
  display.write(247);                       // Print units
  display.println();                     

  // Display UTC time
  display.print("UTC: ");                   // Print "UTC: " label
  if (gps.time.isValid()) {                 // Check if time data is valid
    // Format time as HH:MM:SS using printf-style formatting
    display.printf("%02d:%02d:%02d\n",
                   gps.time.hour(),
                   gps.time.minute(),
                   gps.time.second());
  } else {
    display.println("Invalid");             // Show "Invalid" if no time fix
  }

  // Display current date
  display.print("Date: ");                   // Print "Date: " label
  if (gps.date.isValid()) {                  // Check if date data is valid
    // Format date as DAY/MONTH/YEAR using printf-style formatting
    display.printf("%02d/%02d/%04d\n",
                  gps.date.day(),
                  gps.date.month(),
                  gps.date.year());
  } else {
    display.println("Invalid");               // Show "Invalid" if no time fix
  }
  display.display();                        // Push buffer to OLED screen (refresh display)
}

// Include libraries for GPS parsing, I2C communication, graphics, and OLED display
#include <TinyGPSPlus.h>
#include <Wire.h>                    // I2C communication library
#include <Adafruit_GFX.h>            // Graphics library for OLED
#include <Adafruit_SSD1306.h>        // SSD1306 OLED display driver

// OLED display dimensions (128x64 pixels standard)
#define SCREEN_WIDTH 128    // OLED screen width in pixels
#define SCREEN_HEIGHT 64    // OLED screen height in pixels
#define ADDRESS 0x3C        // Replace this with the I2C address of your OLED display

// OLED reset pin configuration (-1 means use Arduino reset pin)
#define OLED_RESET -1                // No dedicated reset pin, share Arduino reset

// Create OLED display object with specified dimensions, I2C interface, and reset pin
Adafruit_SSD1306 display(SCREEN_WIDTH, SCREEN_HEIGHT, &Wire, OLED_RESET);

// Create GPS parser object
TinyGPSPlus gps;                     // TinyGPSPlus object for NMEA sentence parsing

// Define GPS serial port and pin assignments for FireBeetle ESP32S3
#define gpsSerial Serial2              // Use hardware Serial2 (UART2) for GPS
#define RX_PIN 44                      // FireBeetle RX/GPIO44 (RX pin)  GPS TX
#define TX_PIN 43                      // FireBeetle TX/GPIO43 (TX pin)  GPS RX (optional)

// Setup function - runs once at startup
void setup() {
  // Initialize GPS serial port on Serial2 with specified pins and GPS baud rate (9600)
  gpsSerial.begin(9600, SERIAL_8N1, RX_PIN, TX_PIN);  // 8 data bits, no parity, 1 stop bit

  // Initialize OLED display with internal power supply and I2C address
  if (!display.begin(SSD1306_SWITCHCAPVCC, ADDRESS)) {   // Try to start OLED at I2C address
    Serial.println(F("SSD1306 allocation failed"));      // Print error if OLED fails
    for (;;);                                            // Infinite loop if OLED fails
  }

  // Clear OLED display buffer
  display.clearDisplay();

  // Configure OLED text rendering settings
  display.setTextSize(1);               // Set text size to 1 (smallest)
  display.setTextColor(SSD1306_WHITE);  // Set text color to white
  display.setCursor(0, 0);              // Set text cursor to top-left corner (x=0, y=0)

  // Display startup message on OLED
  display.println("Waiting for GPS...");
  display.display();                    // Update OLED with buffer contents
}

// Main loop - runs continuously
void loop() {
  // Read all available GPS data from serial port
  while (gpsSerial.available() > 0) {
    // Read one byte from GPS serial port
    if (gps.encode(gpsSerial.read())) {     // Parse NMEA data, returns true if valid
      displayLocationInfo();                // Update display with GPS data when valid fix
    }
  }

  // Check if 5 seconds passed with no GPS data (less than 10 chars processed)
  if (millis() > 5000 && gps.charsProcessed() < 10) {
    display.clearDisplay();                 // Clear OLED buffer
    display.setCursor(0, 0);                // Reset cursor to top-left
    display.println("No GPS detected!");    // Show error message
    display.display();                      // Update OLED display
    while (true);                           // Stop program execution
  }
}

// Function to display GPS location information on OLED
void displayLocationInfo() {
  display.clearDisplay();                   // Clear previous display content
  display.setCursor(0, 0);                  // Reset cursor to top-left corner

  // Display Latitude
  display.print("Lat: ");                   // Print "Lat: " label
  if (gps.location.isValid()) {             // Check if latitude data is valid
    display.println(gps.location.lat(), 6); // Print latitude with 6 decimal places
  } else {
    display.println("Invalid");             // Show "Invalid" if no valid fix
  }

  // Display Longitude
  display.print("Lng: ");                   // Print "Lng: " label
  if (gps.location.isValid()) {             // Check if longitude data is valid
    display.println(gps.location.lng(), 6); // Print longitude with 6 decimal places
  } else {
    display.println("Invalid");             // Show "Invalid" if no valid fix
  }

  // Display number of satellites
  display.print("Sats: ");                  // Print "Sats: " label
  display.println(gps.satellites.value());  // Print satellite count

  // Display altitude
  display.print("Alt: ");                   // Print "Alt: " label
  display.print(gps.altitude.meters());     // Print altitude in meters
  display.println(" m");                    // Print units

  // Display ground speed
  display.print("Spd: ");                   // Print "Spd: " label
  display.print(gps.speed.kmph());          // Print speed in km/h
  display.println(" km/h");                 // Print units

  // Display course / direction of movement
  display.print("Course: ");                // Print "Course: " label
  display.print(gps.course.deg());          // Print couse in degrees
  display.write(247);                       // Print units
  display.println();                     

  // Display UTC time
  display.print("UTC: ");                   // Print "UTC: " label
  if (gps.time.isValid()) {                 // Check if time data is valid
    // Format time as HH:MM:SS using printf-style formatting
    display.printf("%02d:%02d:%02d\n",
                   gps.time.hour(),
                   gps.time.minute(),
                   gps.time.second());
  } else {
    display.println("Invalid");             // Show "Invalid" if no time fix
  }

  // Display current date
  display.print("Date: ");                   // Print "Date: " label
  if (gps.date.isValid()) {                  // Check if date data is valid
    // Format date as DAY/MONTH/YEAR using printf-style formatting
    display.printf("%02d/%02d/%04d\n",
                  gps.date.day(),
                  gps.date.month(),
                  gps.date.year());
  } else {
    display.println("Invalid");               // Show "Invalid" if no time fix
  }
  display.display();                        // Push buffer to OLED screen (refresh display)
}

// Include libraries for GPS parsing, I2C communication, graphics, and OLED display
#include <TinyGPSPlus.h>
#include <Wire.h>                    // I2C communication library
#include <Adafruit_GFX.h>            // Graphics library for OLED
#include <Adafruit_SSD1306.h>        // SSD1306 OLED display driver

// OLED display dimensions (128x64 pixels standard)
#define SCREEN_WIDTH 128    // OLED screen width in pixels
#define SCREEN_HEIGHT 64    // OLED screen height in pixels
#define ADDRESS 0x3C        // Replace this with the I2C address of your OLED display

// OLED reset pin configuration (-1 means use Arduino reset pin)
#define OLED_RESET -1                // No dedicated reset pin, share Arduino reset

// Create OLED display object with specified dimensions, I2C interface, and reset pin
Adafruit_SSD1306 display(SCREEN_WIDTH, SCREEN_HEIGHT, &Wire, OLED_RESET);

// Create GPS parser object
TinyGPSPlus gps;                     // TinyGPSPlus object for NMEA sentence parsing

// Define GPS serial port and pin assignments for ESP32 DEV KIT V1
#define gpsSerial Serial2              // Use hardware Serial2 (UART2) for GPS
#define RX_PIN 16                      // ESP32 RX2/GPIO16 (RX pin)  GPS TX
#define TX_PIN 17                      // ESP32 TX2/GPIO17 (TX pin)  GPS RX (optional)

// Setup function - runs once at startup
void setup() {
  // Initialize GPS serial port on Serial2 with specified pins and GPS baud rate (9600)
  gpsSerial.begin(9600, SERIAL_8N1, RX_PIN, TX_PIN);  // 8 data bits, no parity, 1 stop bit

  // Initialize OLED display with internal power supply and I2C address
  if (!display.begin(SSD1306_SWITCHCAPVCC, ADDRESS)) {   // Try to start OLED at I2C address
    Serial.println(F("SSD1306 allocation failed"));      // Print error if OLED fails
    for (;;);                                            // Infinite loop if OLED fails
  }

  // Clear OLED display buffer
  display.clearDisplay();

  // Configure OLED text rendering settings
  display.setTextSize(1);               // Set text size to 1 (smallest)
  display.setTextColor(SSD1306_WHITE);  // Set text color to white
  display.setCursor(0, 0);              // Set text cursor to top-left corner (x=0, y=0)

  // Display startup message on OLED
  display.println("Waiting for GPS...");
  display.display();                    // Update OLED with buffer contents
}

// Main loop - runs continuously
void loop() {
  // Read all available GPS data from serial port
  while (gpsSerial.available() > 0) {
    // Read one byte from GPS serial port
    if (gps.encode(gpsSerial.read())) {     // Parse NMEA sentence, returns true if valid
      displayLocationInfo();                // Update display with GPS data when valid fix
    }
  }

  // Check if 5 seconds passed with no GPS data (less than 10 chars processed)
  if (millis() > 5000 && gps.charsProcessed() < 10) {
    display.clearDisplay();                 // Clear OLED buffer
    display.setCursor(0, 0);                // Reset cursor to top-left
    display.println("No GPS detected!");    // Show error message
    display.display();                      // Update OLED display
    while (true);                           // Stop program execution
  }
}

// Function to display GPS location information on OLED
void displayLocationInfo() {
  display.clearDisplay();                   // Clear previous display content
  display.setCursor(0, 0);                  // Reset cursor to top-left corner

  // Display Latitude
  display.print("Lat: ");                   // Print "Lat: " label
  if (gps.location.isValid()) {             // Check if latitude data is valid
    display.println(gps.location.lat(), 6); // Print latitude with 6 decimal places
  } else {
    display.println("Invalid");             // Show "Invalid" if no valid fix
  }

  // Display Longitude
  display.print("Lng: ");                   // Print "Lng: " label
  if (gps.location.isValid()) {             // Check if longitude data is valid
    display.println(gps.location.lng(), 6); // Print longitude with 6 decimal places
  } else {
    display.println("Invalid");             // Show "Invalid" if no valid fix
  }

  // Display number of satellites
  display.print("Sats: ");                  // Print "Sats: " label
  display.println(gps.satellites.value());  // Print satellite count

  // Display altitude
  display.print("Alt: ");                   // Print "Alt: " label
  display.print(gps.altitude.meters());     // Print altitude in meters
  display.println(" m");                    // Print units

  // Display ground speed
  display.print("Spd: ");                   // Print "Spd: " label
  display.print(gps.speed.kmph());          // Print speed in km/h
  display.println(" km/h");                 // Print units

  // Display course / direction of movement
  display.print("Course: ");                // Print "Course: " label
  display.print(gps.course.deg());          // Print couse in degrees
  display.write(247);                       // Print units
  display.println();                     

  // Display UTC time
  display.print("UTC: ");                   // Print "UTC: " label
  if (gps.time.isValid()) {                 // Check if time data is valid
    // Format time as HH:MM:SS using printf-style formatting
    display.printf("%02d:%02d:%02d\n",
                   gps.time.hour(),
                   gps.time.minute(),
                   gps.time.second());
  } else {
    display.println("Invalid");             // Show "Invalid" if no time fix
  }

  // Display current date
  display.print("Date: ");                   // Print "Date: " label
  if (gps.date.isValid()) {                  // Check if date data is valid
    // Format date as DAY/MONTH/YEAR using printf-style formatting
    display.printf("%02d/%02d/%04d\n",
                  gps.date.day(),
                  gps.date.month(),
                  gps.date.year());
  } else {
    display.println("Invalid");               // Show "Invalid" if no time fix
  }
  display.display();                        // Push buffer to OLED screen (refresh display)
}

Credits

Vijay Kumar

2 projects • 1 follower

CS student building IoT solutions, developing for 3+ years, started hardware journey through hands-on tinkering and experiments.

Getting Started with Ai-Thinker GP-02: BDS/GPS/GNSS

Things used in this project

Hardware components

Software apps and online services

Story

🚀 Introduction

📦 Device Overview

🛰️ Satellite Navigation Process

⚙️ GP‑02 Module Internals

🔌 Microcontroller Communication (TX/RX)

🛠️ Prerequisites

📚 Installing the Required Libraries

📐 Circuit Diagrams

💻 Uploading the Code

📲 Flashing GP‑02 Module Codes

📡 Positioning the Ceramic Antenna

📷 Guide Illustration: GNSS Module with Boards

📑 GP‑02 GNSS Module Technical Details

✅ Conclusion

Schematics

Circuit Diagram

Circuit Diagram

Circuit Diagram

Circuit Diagram

Code

Seeed Studio XIAO ESP32 S3

Seeed Studio XIAO ESP32 C3

DF Robot FireBeetle 2 ESP32 S3

ESP32 DEV KIT V1

Credits

Vijay Kumar

Comments

Embed the widget on your own site

Getting Started with Ai-Thinker GP-02: BDS/GPS/GNSS

Getting Started with Ai-Thinker GP-02: BDS/GPS/GNSS

Things used in this project

Hardware components

Software apps and online services

Story

🚀 Introduction

📦 Device Overview

🛰️ Satellite Navigation Process

⚙️ GP‑02 Module Internals

🔌 Microcontroller Communication (TX/RX)

🛠️ Prerequisites

📚 Installing the Required Libraries

📐 Circuit Diagrams

💻 Uploading the Code

📲 Flashing GP‑02 Module Codes

📡 Positioning the Ceramic Antenna

📷 Guide Illustration: GNSS Module with Boards

📑 GP‑02 GNSS Module Technical Details

✅ Conclusion

Schematics

Circuit Diagram

Circuit Diagram

Circuit Diagram

Circuit Diagram

Code

Seeed Studio XIAO ESP32 S3

Seeed Studio XIAO ESP32 C3

DF Robot FireBeetle 2 ESP32 S3

ESP32 DEV KIT V1

Credits

Vijay Kumar

Comments

Related channels and tags