924 lines
33 KiB
HTML
924 lines
33 KiB
HTML
<!DOCTYPE html>
|
|
<html lang="en">
|
|
<head>
|
|
<meta charset="UTF-8">
|
|
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
|
<title>ESP32-C5 GPS Synchronization Guide</title>
|
|
<style>
|
|
:root {
|
|
--primary-color: #2c3e50;
|
|
--secondary-color: #3498db;
|
|
--accent-color: #e74c3c;
|
|
--success-color: #27ae60;
|
|
--code-bg: #f4f4f4;
|
|
--border-color: #ddd;
|
|
}
|
|
|
|
* {
|
|
margin: 0;
|
|
padding: 0;
|
|
box-sizing: border-box;
|
|
}
|
|
|
|
body {
|
|
font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Oxygen, Ubuntu, Cantarell, sans-serif;
|
|
line-height: 1.6;
|
|
color: #333;
|
|
max-width: 1200px;
|
|
margin: 0 auto;
|
|
padding: 20px;
|
|
background-color: #f9f9f9;
|
|
}
|
|
|
|
header {
|
|
background: linear-gradient(135deg, var(--primary-color), var(--secondary-color));
|
|
color: white;
|
|
padding: 40px 30px;
|
|
border-radius: 8px;
|
|
margin-bottom: 30px;
|
|
box-shadow: 0 4px 6px rgba(0,0,0,0.1);
|
|
}
|
|
|
|
h1 {
|
|
font-size: 2.5em;
|
|
margin-bottom: 10px;
|
|
}
|
|
|
|
.subtitle {
|
|
font-size: 1.2em;
|
|
opacity: 0.9;
|
|
}
|
|
|
|
h2 {
|
|
color: var(--primary-color);
|
|
border-bottom: 3px solid var(--secondary-color);
|
|
padding-bottom: 10px;
|
|
margin: 30px 0 20px 0;
|
|
font-size: 1.8em;
|
|
}
|
|
|
|
h3 {
|
|
color: var(--secondary-color);
|
|
margin: 25px 0 15px 0;
|
|
font-size: 1.4em;
|
|
}
|
|
|
|
h4 {
|
|
color: var(--primary-color);
|
|
margin: 20px 0 10px 0;
|
|
font-size: 1.1em;
|
|
}
|
|
|
|
.section {
|
|
background: white;
|
|
padding: 30px;
|
|
margin-bottom: 25px;
|
|
border-radius: 8px;
|
|
box-shadow: 0 2px 4px rgba(0,0,0,0.05);
|
|
}
|
|
|
|
.info-box {
|
|
background-color: #e8f4f8;
|
|
border-left: 4px solid var(--secondary-color);
|
|
padding: 15px 20px;
|
|
margin: 20px 0;
|
|
border-radius: 4px;
|
|
}
|
|
|
|
.warning-box {
|
|
background-color: #fff3cd;
|
|
border-left: 4px solid #ffc107;
|
|
padding: 15px 20px;
|
|
margin: 20px 0;
|
|
border-radius: 4px;
|
|
}
|
|
|
|
.success-box {
|
|
background-color: #d4edda;
|
|
border-left: 4px solid var(--success-color);
|
|
padding: 15px 20px;
|
|
margin: 20px 0;
|
|
border-radius: 4px;
|
|
}
|
|
|
|
.wiring-table {
|
|
width: 100%;
|
|
border-collapse: collapse;
|
|
margin: 20px 0;
|
|
box-shadow: 0 2px 4px rgba(0,0,0,0.1);
|
|
}
|
|
|
|
.wiring-table th,
|
|
.wiring-table td {
|
|
padding: 12px 15px;
|
|
text-align: left;
|
|
border: 1px solid var(--border-color);
|
|
}
|
|
|
|
.wiring-table th {
|
|
background-color: var(--secondary-color);
|
|
color: white;
|
|
font-weight: 600;
|
|
}
|
|
|
|
.wiring-table tr:nth-child(even) {
|
|
background-color: #f8f9fa;
|
|
}
|
|
|
|
.wiring-table td:first-child {
|
|
font-weight: 600;
|
|
color: var(--primary-color);
|
|
}
|
|
|
|
pre {
|
|
background-color: var(--code-bg);
|
|
border: 1px solid var(--border-color);
|
|
border-radius: 4px;
|
|
padding: 20px;
|
|
overflow-x: auto;
|
|
margin: 15px 0;
|
|
font-family: 'Courier New', Courier, monospace;
|
|
font-size: 0.9em;
|
|
line-height: 1.4;
|
|
}
|
|
|
|
code {
|
|
background-color: var(--code-bg);
|
|
padding: 2px 6px;
|
|
border-radius: 3px;
|
|
font-family: 'Courier New', Courier, monospace;
|
|
font-size: 0.9em;
|
|
}
|
|
|
|
pre code {
|
|
background-color: transparent;
|
|
padding: 0;
|
|
}
|
|
|
|
.pinout-diagram {
|
|
text-align: center;
|
|
margin: 30px 0;
|
|
padding: 20px;
|
|
background-color: #f8f9fa;
|
|
border-radius: 8px;
|
|
}
|
|
|
|
.pinout-diagram img {
|
|
max-width: 100%;
|
|
height: auto;
|
|
border: 2px solid var(--border-color);
|
|
border-radius: 4px;
|
|
}
|
|
|
|
.component-list {
|
|
list-style: none;
|
|
padding: 0;
|
|
}
|
|
|
|
.component-list li {
|
|
padding: 12px 15px;
|
|
margin: 8px 0;
|
|
background-color: #f8f9fa;
|
|
border-left: 4px solid var(--success-color);
|
|
border-radius: 4px;
|
|
}
|
|
|
|
.component-list li strong {
|
|
color: var(--primary-color);
|
|
}
|
|
|
|
a {
|
|
color: var(--secondary-color);
|
|
text-decoration: none;
|
|
font-weight: 500;
|
|
}
|
|
|
|
a:hover {
|
|
text-decoration: underline;
|
|
color: var(--primary-color);
|
|
}
|
|
|
|
.btn {
|
|
display: inline-block;
|
|
padding: 10px 20px;
|
|
background-color: var(--secondary-color);
|
|
color: white;
|
|
border-radius: 4px;
|
|
text-decoration: none;
|
|
margin: 5px;
|
|
transition: background-color 0.3s;
|
|
}
|
|
|
|
.btn:hover {
|
|
background-color: var(--primary-color);
|
|
text-decoration: none;
|
|
}
|
|
|
|
.ascii-diagram {
|
|
background-color: #1e1e1e;
|
|
color: #d4d4d4;
|
|
padding: 20px;
|
|
border-radius: 4px;
|
|
font-family: 'Courier New', Courier, monospace;
|
|
overflow-x: auto;
|
|
margin: 20px 0;
|
|
}
|
|
|
|
footer {
|
|
text-align: center;
|
|
margin-top: 50px;
|
|
padding: 20px;
|
|
color: #666;
|
|
border-top: 2px solid var(--border-color);
|
|
}
|
|
|
|
@media print {
|
|
body {
|
|
background-color: white;
|
|
}
|
|
.section {
|
|
box-shadow: none;
|
|
page-break-inside: avoid;
|
|
}
|
|
pre {
|
|
page-break-inside: avoid;
|
|
}
|
|
}
|
|
</style>
|
|
</head>
|
|
<body>
|
|
<header>
|
|
<h1>ESP32-C5 GPS Synchronization Guide</h1>
|
|
<div class="subtitle">Precision Timing for WiFi Collapse Detection with iperf2 Correlation</div>
|
|
</header>
|
|
|
|
<div class="section">
|
|
<h2>Overview</h2>
|
|
<p>This guide demonstrates how to synchronize an ESP32-C5-DevKitC-1-N8R4 to GPS time using a GPS module with PPS (Pulse Per Second) output. This enables precise timestamp correlation between WiFi collapse detector events and iperf2 latency measurements running on a GPS-synced Raspberry Pi 5.</p>
|
|
|
|
<div class="info-box">
|
|
<strong>Key Features:</strong>
|
|
<ul style="margin: 10px 0 0 20px;">
|
|
<li>Monotonic clock for interval measurements (never jumps backward)</li>
|
|
<li>GPS UTC timestamp for correlation with iperf2 data</li>
|
|
<li>Microsecond-precision PPS synchronization</li>
|
|
<li>Suitable for 32+ device deployments</li>
|
|
</ul>
|
|
</div>
|
|
</div>
|
|
|
|
<div class="section">
|
|
<h2>Required Hardware</h2>
|
|
<ul class="component-list">
|
|
<li><strong>ESP32-C5-DevKitC-1-N8R4</strong> - Development board with WiFi 6/6E, 4MB PSRAM, dual USB-C ports</li>
|
|
<li><strong>MakerFocus GT-U7 GPS Module</strong> - With PPS output and IPEX active antenna
|
|
<ul style="margin: 10px 0 0 20px;">
|
|
<li>Operating Voltage: 3.6V - 5V (works perfectly with ESP32's 3.3V)</li>
|
|
<li>Baud Rate: 9600</li>
|
|
<li>Compatible with NEO-6M (same NMEA format)</li>
|
|
<li>Includes: EEPROM, USB interface, IPEX antenna</li>
|
|
</ul>
|
|
</li>
|
|
<li><strong>Female-to-Female Dupont Wires</strong> - 4-5 wires minimum
|
|
<a href="https://www.amazon.com/Elegoo-EL-CP-004-Multicolored-Breadboard-arduino/dp/B01EV70C78" class="btn" target="_blank">Buy ELEGOO Kit - $6.99</a>
|
|
</li>
|
|
<li><strong>USB-C Cable</strong> - For programming and power (use UART USB port on right side)</li>
|
|
<li><strong>Raspberry Pi 5</strong> - Already GPS-synced, running iperf2</li>
|
|
</ul>
|
|
|
|
<div class="info-box">
|
|
<strong>Note on USB Ports:</strong><br>
|
|
The ESP32-C5 has TWO USB-C ports:
|
|
<ul style="margin: 10px 0 0 20px;">
|
|
<li><strong>UART USB (Right):</strong> USB-to-UART bridge - recommended for programming and serial monitor</li>
|
|
<li><strong>ESP32 USB (Left):</strong> Native USB on chip (GPIO13/14) - supports USB 2.0 and JTAG debugging</li>
|
|
</ul>
|
|
For development, use the <strong>UART USB port (right side)</strong> as it's more reliable for flashing and monitoring.
|
|
</div>
|
|
|
|
<div class="success-box">
|
|
<strong>✓ GT-U7 & ESP32-C5 Compatibility:</strong><br>
|
|
The MakerFocus GT-U7 operates at 3.6V-5V and is fully compatible with the ESP32-C5's 3.3V power output. You can safely connect GT-U7's VCC directly to the ESP32's 3V3 pin (J1 Pin 1). The GT-U7's logic levels are also 3.3V/5V tolerant, making it a perfect match.
|
|
</div>
|
|
</div>
|
|
|
|
<div class="section">
|
|
<h2>Pin Connections</h2>
|
|
|
|
<h3>ESP32-C5 Pinout</h3>
|
|
<div class="pinout-diagram">
|
|
<img src="https://docs.espressif.com/projects/esp-dev-kits/en/latest/_images/esp32-c5-devkitc-1-pin-layout_v1.2.png"
|
|
alt="ESP32-C5 Pinout Diagram">
|
|
<p style="margin-top: 10px; font-size: 0.9em; color: #666;">
|
|
Source: <a href="https://docs.espressif.com/projects/esp-dev-kits/en/latest/esp32c5/esp32-c5-devkitc-1/user_guide.html" target="_blank">Espressif ESP32-C5 Documentation</a>
|
|
</p>
|
|
</div>
|
|
|
|
<h3>Wiring Diagram</h3>
|
|
<table class="wiring-table">
|
|
<thead>
|
|
<tr>
|
|
<th>GT-U7 GPS Pin</th>
|
|
<th>ESP32-C5 Pin</th>
|
|
<th>Header Location</th>
|
|
<th>GPIO Number</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr>
|
|
<td>VCC</td>
|
|
<td>Pin 1</td>
|
|
<td>J1 (Left Side)</td>
|
|
<td>3V3 (3.3V works perfect!)</td>
|
|
</tr>
|
|
<tr>
|
|
<td>GND</td>
|
|
<td>Pin 15</td>
|
|
<td>J1 (Left Side)</td>
|
|
<td>GND</td>
|
|
</tr>
|
|
<tr>
|
|
<td>TXD (NMEA Data)</td>
|
|
<td>Pin 8</td>
|
|
<td>J3 (Right Side)</td>
|
|
<td>GPIO4 (RX)</td>
|
|
</tr>
|
|
<tr>
|
|
<td>PPS (Pulse/Second)</td>
|
|
<td>Pin 6</td>
|
|
<td>J1 (Left Side)</td>
|
|
<td>GPIO1</td>
|
|
</tr>
|
|
<tr>
|
|
<td>RXD (Optional)</td>
|
|
<td>Pin 9</td>
|
|
<td>J3 (Right Side)</td>
|
|
<td>GPIO5 (TX)</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
|
|
<h3>Visual Connection Guide</h3>
|
|
<div style="background: #2c3e50; padding: 30px; border-radius: 8px; margin: 20px 0;">
|
|
<pre style="color: #ecf0f1; font-size: 1.2em; line-height: 1.8; margin: 0; font-family: 'Courier New', monospace; font-weight: bold;">
|
|
GT-U7 GPS Module ESP32-C5-DevKitC-1 Board
|
|
---------------- ═══════════════════════════════════════
|
|
|
|
<span style="color: #f39c12;"> ┌─── J1 (LEFT) ──┐ ┌── J3 (RIGHT) ──┐</span>
|
|
<span style="color: #27ae60;">VCC (3.3V-5V) ────────→ │ Pin 1: 3V3 │ │ │</span>
|
|
│ Pin 2: RST │ │ │
|
|
│ Pin 3: GPIO2 │ │ │
|
|
│ Pin 4: GPIO3 │ │ │
|
|
│ Pin 5: GPIO0 │ │ │
|
|
<span style="color: #27ae60;">PPS (pulse) ────────→ │ Pin 6: GPIO1 │ │ │</span>
|
|
│ Pin 7: GPIO6 │ │ │
|
|
│ Pin 8: GPIO7 │ │ │
|
|
│ Pin 9: GPIO8 │ │ │
|
|
│ Pin 10: GPIO9 │ │ │
|
|
│ Pin 11: GPIO10 │ │ │
|
|
│ Pin 12: GPIO26 │ │ │
|
|
│ Pin 13: GPIO25 │ │ │
|
|
│ Pin 14: 5V │ │ │
|
|
<span style="color: #27ae60;">GND ────────→ │ Pin 15: GND │ │ │</span>
|
|
│ Pin 16: NC │ │ │
|
|
└────────────────┘ │ │
|
|
│ Pin 1: GND │
|
|
│ Pin 2: TX │
|
|
│ Pin 3: RX │
|
|
│ Pin 4: GPIO24 │
|
|
│ Pin 5: GPIO23 │
|
|
│ Pin 6: NC │
|
|
│ Pin 7: GPIO27 │
|
|
<span style="color: #27ae60;">TXD (data out) ──────────────────────────→ │ Pin 8: GPIO4 │</span>
|
|
<span style="color: #95a5a6;">RXD (optional) ←────────────────────────────│ Pin 9: GPIO5 │</span>
|
|
│ Pin 10: NC │
|
|
│ Pin 11: GPIO28 │
|
|
│ Pin 12: GND │
|
|
│ Pin 13: GPIO14 │
|
|
│ Pin 14: GPIO13 │
|
|
│ Pin 15: GND │
|
|
│ Pin 16: NC │
|
|
└────────────────┘
|
|
|
|
<span style="color: #3498db;">━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
|
GT-U7 IPEX ANTENNA:
|
|
• Connect active antenna to GT-U7's IPEX connector
|
|
• Place antenna with clear view of sky for best reception
|
|
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━</span>
|
|
|
|
<span style="color: #e74c3c;">REQUIRED CONNECTIONS (4 wires):</span>
|
|
<span style="color: #27ae60;"> 1. GT-U7 VCC → J1 Pin 1 (3V3)
|
|
2. GT-U7 GND → J1 Pin 15 (GND)
|
|
3. GT-U7 TXD → J3 Pin 8 (GPIO4)
|
|
4. GT-U7 PPS → J1 Pin 6 (GPIO1)</span>
|
|
</pre>
|
|
</div>
|
|
|
|
<div class="warning-box">
|
|
<strong>⚠️ Important Notes:</strong>
|
|
<ul style="margin: 10px 0 0 20px;">
|
|
<li>Use 3.3V power only - do NOT connect to 5V</li>
|
|
<li>GPIO2, GPIO3, GPIO7, GPIO25-28 are strapping pins - avoid for general use</li>
|
|
<li>N8R4 variant has 4MB PSRAM using internal pins - GPIO4/5 are safe</li>
|
|
</ul>
|
|
</div>
|
|
</div>
|
|
|
|
<div class="section">
|
|
<h2>Software Implementation</h2>
|
|
|
|
<h3>Project Structure</h3>
|
|
<pre>
|
|
your_project/
|
|
├── CMakeLists.txt
|
|
└── main/
|
|
├── CMakeLists.txt
|
|
├── main.c
|
|
├── gps_sync.h
|
|
└── gps_sync.c
|
|
</pre>
|
|
|
|
<h3>gps_sync.h - Header File</h3>
|
|
<pre><code>#pragma once
|
|
|
|
#include <stdint.h>
|
|
#include <time.h>
|
|
#include "freertos/FreeRTOS.h"
|
|
#include "freertos/semphr.h"
|
|
|
|
typedef struct {
|
|
int64_t monotonic_us; // Never jumps backward
|
|
int64_t gps_us; // GPS UTC time in microseconds
|
|
bool synced; // true if GPS has valid fix
|
|
} gps_timestamp_t;
|
|
|
|
// Initialize GPS sync system
|
|
void gps_sync_init(void);
|
|
|
|
// Get current timestamp
|
|
gps_timestamp_t gps_get_timestamp(void);
|
|
|
|
// Check if GPS is synced
|
|
bool gps_is_synced(void);</code></pre>
|
|
|
|
<h3>gps_sync.c - Implementation</h3>
|
|
<pre><code>#include "gps_sync.h"
|
|
#include "driver/gpio.h"
|
|
#include "driver/uart.h"
|
|
#include "esp_timer.h"
|
|
#include "esp_log.h"
|
|
#include <string.h>
|
|
#include <time.h>
|
|
|
|
#define GPS_UART_NUM UART_NUM_1
|
|
#define GPS_RX_PIN GPIO_NUM_4
|
|
#define GPS_TX_PIN GPIO_NUM_5
|
|
#define PPS_GPIO GPIO_NUM_1
|
|
#define GPS_BAUD_RATE 9600
|
|
#define UART_BUF_SIZE 1024
|
|
|
|
static const char *TAG = "GPS_SYNC";
|
|
|
|
// GPS sync state
|
|
static int64_t monotonic_offset_us = 0;
|
|
static volatile int64_t last_pps_monotonic = 0;
|
|
static volatile time_t next_pps_gps_second = 0;
|
|
static bool gps_has_fix = false;
|
|
static SemaphoreHandle_t sync_mutex;
|
|
|
|
// PPS interrupt - captures exact monotonic time at second boundary
|
|
static void IRAM_ATTR pps_isr_handler(void* arg) {
|
|
last_pps_monotonic = esp_timer_get_time();
|
|
}
|
|
|
|
// Parse GPS time from NMEA sentence
|
|
static bool parse_gprmc(const char* nmea, struct tm* tm_out, bool* valid) {
|
|
if (strncmp(nmea, "$GPRMC", 6) != 0 && strncmp(nmea, "$GNRMC", 6) != 0) {
|
|
return false;
|
|
}
|
|
|
|
char *p = strchr(nmea, ',');
|
|
if (!p) return false;
|
|
|
|
// Time field
|
|
p++;
|
|
int hour, min, sec;
|
|
if (sscanf(p, "%2d%2d%2d", &hour, &min, &sec) != 3) {
|
|
return false;
|
|
}
|
|
|
|
// Status field (A=valid, V=invalid)
|
|
p = strchr(p, ',');
|
|
if (!p) return false;
|
|
p++;
|
|
*valid = (*p == 'A');
|
|
|
|
// Skip to date field (8 commas ahead from time)
|
|
for (int i = 0; i < 7; i++) {
|
|
p = strchr(p, ',');
|
|
if (!p) return false;
|
|
p++;
|
|
}
|
|
|
|
// Date field: ddmmyy
|
|
int day, month, year;
|
|
if (sscanf(p, "%2d%2d%2d", &day, &month, &year) != 3) {
|
|
return false;
|
|
}
|
|
|
|
year += (year < 80) ? 2000 : 1900;
|
|
|
|
tm_out->tm_sec = sec;
|
|
tm_out->tm_min = min;
|
|
tm_out->tm_hour = hour;
|
|
tm_out->tm_mday = day;
|
|
tm_out->tm_mon = month - 1;
|
|
tm_out->tm_year = year - 1900;
|
|
tm_out->tm_isdst = 0;
|
|
|
|
return true;
|
|
}
|
|
|
|
// GPS processing task
|
|
static void gps_task(void* arg) {
|
|
char line[128];
|
|
int pos = 0;
|
|
|
|
while (1) {
|
|
uint8_t data;
|
|
int len = uart_read_bytes(GPS_UART_NUM, &data, 1, 100 / portTICK_PERIOD_MS);
|
|
|
|
if (len > 0) {
|
|
if (data == '\n') {
|
|
line[pos] = '\0';
|
|
|
|
struct tm gps_tm;
|
|
bool valid;
|
|
if (parse_gprmc(line, &gps_tm, &valid)) {
|
|
if (valid) {
|
|
time_t gps_time = mktime(&gps_tm);
|
|
|
|
xSemaphoreTake(sync_mutex, portMAX_DELAY);
|
|
next_pps_gps_second = gps_time + 1;
|
|
xSemaphoreGive(sync_mutex);
|
|
|
|
vTaskDelay(pdMS_TO_TICKS(300));
|
|
|
|
xSemaphoreTake(sync_mutex, portMAX_DELAY);
|
|
if (last_pps_monotonic > 0) {
|
|
int64_t gps_us = (int64_t)next_pps_gps_second * 1000000LL;
|
|
int64_t new_offset = gps_us - last_pps_monotonic;
|
|
|
|
if (monotonic_offset_us == 0) {
|
|
monotonic_offset_us = new_offset;
|
|
} else {
|
|
// Low-pass filter: 90% old + 10% new
|
|
monotonic_offset_us = (monotonic_offset_us * 9 + new_offset) / 10;
|
|
}
|
|
|
|
gps_has_fix = true;
|
|
|
|
ESP_LOGI(TAG, "GPS sync: %04d-%02d-%02d %02d:%02d:%02d, offset=%lld us",
|
|
gps_tm.tm_year + 1900, gps_tm.tm_mon + 1, gps_tm.tm_mday,
|
|
gps_tm.tm_hour, gps_tm.tm_min, gps_tm.tm_sec,
|
|
monotonic_offset_us);
|
|
}
|
|
xSemaphoreGive(sync_mutex);
|
|
} else {
|
|
gps_has_fix = false;
|
|
}
|
|
}
|
|
|
|
pos = 0;
|
|
} else if (pos < sizeof(line) - 1) {
|
|
line[pos++] = data;
|
|
}
|
|
}
|
|
}
|
|
}
|
|
|
|
void gps_sync_init(void) {
|
|
ESP_LOGI(TAG, "Initializing GPS sync");
|
|
|
|
sync_mutex = xSemaphoreCreateMutex();
|
|
|
|
uart_config_t uart_config = {
|
|
.baud_rate = GPS_BAUD_RATE,
|
|
.data_bits = UART_DATA_8_BITS,
|
|
.parity = UART_PARITY_DISABLE,
|
|
.stop_bits = UART_STOP_BITS_1,
|
|
.flow_ctrl = UART_HW_FLOWCTRL_DISABLE,
|
|
.source_clk = UART_SCLK_DEFAULT,
|
|
};
|
|
|
|
ESP_ERROR_CHECK(uart_driver_install(GPS_UART_NUM, UART_BUF_SIZE, 0, 0, NULL, 0));
|
|
ESP_ERROR_CHECK(uart_param_config(GPS_UART_NUM, &uart_config));
|
|
ESP_ERROR_CHECK(uart_set_pin(GPS_UART_NUM, GPS_TX_PIN, GPS_RX_PIN,
|
|
UART_PIN_NO_CHANGE, UART_PIN_NO_CHANGE));
|
|
|
|
gpio_config_t io_conf = {
|
|
.intr_type = GPIO_INTR_POSEDGE,
|
|
.mode = GPIO_MODE_INPUT,
|
|
.pin_bit_mask = (1ULL << PPS_GPIO),
|
|
.pull_up_en = GPIO_PULLUP_ENABLE,
|
|
.pull_down_en = GPIO_PULLDOWN_DISABLE,
|
|
};
|
|
ESP_ERROR_CHECK(gpio_config(&io_conf));
|
|
|
|
ESP_ERROR_CHECK(gpio_install_isr_service(0));
|
|
ESP_ERROR_CHECK(gpio_isr_handler_add(PPS_GPIO, pps_isr_handler, NULL));
|
|
|
|
xTaskCreate(gps_task, "gps_task", 4096, NULL, 5, NULL);
|
|
|
|
ESP_LOGI(TAG, "GPS sync initialized (RX=GPIO%d, PPS=GPIO%d)", GPS_RX_PIN, PPS_GPIO);
|
|
}
|
|
|
|
gps_timestamp_t gps_get_timestamp(void) {
|
|
gps_timestamp_t ts;
|
|
|
|
xSemaphoreTake(sync_mutex, portMAX_DELAY);
|
|
ts.monotonic_us = esp_timer_get_time();
|
|
ts.gps_us = ts.monotonic_us + monotonic_offset_us;
|
|
ts.synced = gps_has_fix;
|
|
xSemaphoreGive(sync_mutex);
|
|
|
|
return ts;
|
|
}
|
|
|
|
bool gps_is_synced(void) {
|
|
return gps_has_fix;
|
|
}</code></pre>
|
|
|
|
<h3>main.c - Example Usage</h3>
|
|
<pre><code>#include <stdio.h>
|
|
#include "freertos/FreeRTOS.h"
|
|
#include "freertos/task.h"
|
|
#include "esp_log.h"
|
|
#include "gps_sync.h"
|
|
|
|
static const char *TAG = "MAIN";
|
|
|
|
void log_collapse_event(float nav_duration_us, int rssi) {
|
|
gps_timestamp_t ts = gps_get_timestamp();
|
|
|
|
// CSV format: monotonic_us, gps_us, synced, nav_duration, rssi
|
|
printf("COLLAPSE,%lld,%lld,%d,%.2f,%d\n",
|
|
ts.monotonic_us,
|
|
ts.gps_us,
|
|
ts.synced ? 1 : 0,
|
|
nav_duration_us,
|
|
rssi);
|
|
}
|
|
|
|
void app_main(void) {
|
|
ESP_LOGI(TAG, "Starting GPS sync");
|
|
|
|
gps_sync_init();
|
|
|
|
ESP_LOGI(TAG, "Waiting for GPS fix...");
|
|
while (!gps_is_synced()) {
|
|
vTaskDelay(pdMS_TO_TICKS(1000));
|
|
}
|
|
ESP_LOGI(TAG, "GPS synced!");
|
|
|
|
while (1) {
|
|
gps_timestamp_t ts = gps_get_timestamp();
|
|
|
|
ESP_LOGI(TAG, "Time: mono=%lld gps=%lld synced=%d",
|
|
ts.monotonic_us, ts.gps_us, ts.synced);
|
|
|
|
// Example: log collapse event
|
|
if (ts.monotonic_us % 10000000 < 100000) {
|
|
log_collapse_event(1234.5, -65);
|
|
}
|
|
|
|
vTaskDelay(pdMS_TO_TICKS(1000));
|
|
}
|
|
}</code></pre>
|
|
|
|
<h3>CMakeLists.txt</h3>
|
|
<pre><code>idf_component_register(SRCS "main.c" "gps_sync.c"
|
|
INCLUDE_DIRS ".")</code></pre>
|
|
</div>
|
|
|
|
<div class="section">
|
|
<h2>Building and Flashing</h2>
|
|
|
|
<h3>Setup ESP-IDF Environment</h3>
|
|
<pre><code># Install ESP-IDF (if not already installed)
|
|
# Follow: https://docs.espressif.com/projects/esp-idf/en/latest/esp32c5/get-started/
|
|
|
|
# Set target to ESP32-C5
|
|
idf.py set-target esp32c5
|
|
|
|
# Build the project
|
|
idf.py build
|
|
|
|
# Flash to device
|
|
idf.py flash
|
|
|
|
# Monitor output
|
|
idf.py monitor</code></pre>
|
|
|
|
<div class="success-box">
|
|
<strong>Expected Output:</strong>
|
|
<pre style="background-color: transparent; border: none; padding: 0; margin: 10px 0 0 0;">
|
|
I (500) GPS_SYNC: Initializing GPS sync (RX=GPIO4, PPS=GPIO1)
|
|
I (1000) MAIN: Waiting for GPS fix...
|
|
I (5000) GPS_SYNC: GPS sync: 2025-12-06 18:30:45, offset=1733424645123456 us
|
|
I (5001) MAIN: GPS synced!
|
|
I (6000) MAIN: Time: mono=123456789 gps=1733424645123456 synced=1
|
|
COLLAPSE,123456789,1733424645123456,1,1234.50,-65
|
|
</pre>
|
|
</div>
|
|
</div>
|
|
|
|
<div class="section">
|
|
<h2>Integration with iperf2</h2>
|
|
|
|
<h3>On Raspberry Pi 5 (iperf2 Server)</h3>
|
|
<p>Your Pi is already GPS-synced. Run iperf2 with timestamps:</p>
|
|
<pre><code># Server mode with histograms and trip-times
|
|
iperf -s --histograms --trip-times -i 0.1
|
|
|
|
# Or as client testing against a target
|
|
iperf -c target_ip --histograms --trip-times -i 0.1</code></pre>
|
|
|
|
<h3>Correlation Analysis</h3>
|
|
<p>Both systems now share GPS time. Example Python analysis:</p>
|
|
<pre><code>import pandas as pd
|
|
import matplotlib.pyplot as plt
|
|
|
|
# Load ESP32 collapse events
|
|
esp32_events = pd.read_csv('collapse_events.csv',
|
|
names=['event', 'mono_us', 'gps_us', 'synced', 'nav_dur', 'rssi'],
|
|
parse_dates=['gps_us'],
|
|
date_parser=lambda x: pd.to_datetime(int(x), unit='us'))
|
|
|
|
# Load iperf2 data
|
|
iperf_data = pd.read_csv('iperf_histograms.csv',
|
|
parse_dates=['timestamp'])
|
|
|
|
# Merge on GPS timestamp (within 100ms window)
|
|
merged = pd.merge_asof(iperf_data.sort_values('timestamp'),
|
|
esp32_events.sort_values('gps_us'),
|
|
left_on='timestamp',
|
|
right_on='gps_us',
|
|
tolerance=pd.Timedelta('100ms'),
|
|
direction='nearest')
|
|
|
|
# Plot latency vs collapse events
|
|
fig, ax1 = plt.subplots(figsize=(12, 6))
|
|
ax1.plot(merged['timestamp'], merged['latency_ms'], 'b-', label='Latency')
|
|
ax1.set_ylabel('Latency (ms)', color='b')
|
|
|
|
ax2 = ax1.twinx()
|
|
collapse_times = merged[merged['event'] == 'COLLAPSE']['timestamp']
|
|
ax2.scatter(collapse_times, [1]*len(collapse_times), color='r', marker='x', s=100, label='Collapse')
|
|
ax2.set_ylabel('Collapse Events', color='r')
|
|
|
|
plt.title('WiFi Latency vs Collapse Detection Events')
|
|
plt.show()</code></pre>
|
|
</div>
|
|
|
|
<div class="section">
|
|
<h2>Deployment for 32+ Devices</h2>
|
|
|
|
<h3>Mass Configuration Script</h3>
|
|
<p>Flash and configure multiple ESP32s with unique static IPs:</p>
|
|
<pre><code>#!/bin/bash
|
|
# flash_all.sh
|
|
|
|
START_IP=192.168.1.100
|
|
PORT_BASE=/dev/ttyUSB
|
|
|
|
for i in {0..31}; do
|
|
DEVICE=${PORT_BASE}${i}
|
|
IP=$((START_IP + i))
|
|
|
|
echo "Flashing device $i at $DEVICE with IP 192.168.1.$IP"
|
|
|
|
# Set device-specific config
|
|
idf.py -p $DEVICE -D DEVICE_ID=$i -D STATIC_IP=192.168.1.$IP flash
|
|
|
|
sleep 2
|
|
done
|
|
|
|
echo "All devices flashed!"</code></pre>
|
|
|
|
<h3>Physical Setup Recommendations</h3>
|
|
<ul style="margin: 15px 0 0 20px;">
|
|
<li>Use short (10cm) dupont wires to minimize antenna interference</li>
|
|
<li>Mount GPS modules on top of enclosure for best sky view</li>
|
|
<li>Keep ESP32 antennas clear of metal/GPS modules</li>
|
|
<li>Consider 3D printed stackable enclosures for clean deployment</li>
|
|
<li>Label each device with its static IP for tracking</li>
|
|
</ul>
|
|
</div>
|
|
|
|
<div class="section">
|
|
<h2>Troubleshooting</h2>
|
|
|
|
<h3>No GPS Fix</h3>
|
|
<ul style="margin: 15px 0 0 20px;">
|
|
<li><strong>GT-U7 Antenna:</strong> Ensure IPEX active antenna is properly connected to the module</li>
|
|
<li>Ensure GPS module has clear view of sky (outdoors or near window)</li>
|
|
<li>Cold start can take 30-60 seconds, hot start <1 second</li>
|
|
<li>GT-U7 has excellent sensitivity - works in challenging environments</li>
|
|
<li>Check UART connections (TXD→GPIO4, RXD←GPIO5)</li>
|
|
<li>Verify 3.3V power (measure with multimeter - should be 3.2-3.4V)</li>
|
|
<li>GT-U7 LED should blink when acquiring satellites</li>
|
|
</ul>
|
|
|
|
<h3>PPS Not Working</h3>
|
|
<ul style="margin: 15px 0 0 20px;">
|
|
<li><strong>GT-U7 PPS pin:</strong> Should output 1 pulse per second after GPS lock is achieved</li>
|
|
<li>Verify PPS connection to GPIO1 (J1 Pin 6)</li>
|
|
<li>Check GPIO1 connection with oscilloscope/logic analyzer - should see 3.3V pulse every second</li>
|
|
<li>GT-U7 PPS may require GPS fix first - wait 30-60 seconds outdoors</li>
|
|
<li>Confirm pull-up is enabled in code (already done in example)</li>
|
|
<li>PPS output is 3.3V compatible with ESP32-C5</li>
|
|
</ul>
|
|
|
|
<h3>Time Drift</h3>
|
|
<ul style="margin: 15px 0 0 20px;">
|
|
<li>ESP32 crystal accuracy: ±20ppm (~20μs/sec drift)</li>
|
|
<li>Low-pass filter in code smooths offset updates</li>
|
|
<li>Continuous PPS discipline maintains sync</li>
|
|
<li>For sub-microsecond needs, use external TCXO/OCXO</li>
|
|
</ul>
|
|
</div>
|
|
|
|
<div class="section">
|
|
<h2>Technical Details</h2>
|
|
|
|
<h3>Timing Accuracy</h3>
|
|
<table class="wiring-table">
|
|
<thead>
|
|
<tr>
|
|
<th>Component</th>
|
|
<th>Accuracy</th>
|
|
<th>Notes</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr>
|
|
<td>GT-U7 GPS PPS Output</td>
|
|
<td>±50-100ns</td>
|
|
<td>Compatible with NEO-6M timing specs</td>
|
|
</tr>
|
|
<tr>
|
|
<td>ESP32 Interrupt Latency</td>
|
|
<td>1-5μs typical</td>
|
|
<td>IRAM_ATTR reduces latency</td>
|
|
</tr>
|
|
<tr>
|
|
<td>esp_timer_get_time()</td>
|
|
<td>1μs resolution</td>
|
|
<td>Accuracy ±10-20ppm (crystal dependent)</td>
|
|
</tr>
|
|
<tr>
|
|
<td>Overall System</td>
|
|
<td>~5-10μs</td>
|
|
<td>Sufficient for latency histogram correlation</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
|
|
<h3>Monotonic vs GPS Time</h3>
|
|
<div class="info-box">
|
|
<strong>Monotonic Time (monotonic_us):</strong>
|
|
<ul style="margin: 10px 0 0 20px;">
|
|
<li>Never jumps backward or forward</li>
|
|
<li>Used for measuring intervals and durations</li>
|
|
<li>Not affected by GPS sync adjustments</li>
|
|
<li>Example: Navigation duration, event spacing</li>
|
|
</ul>
|
|
<br>
|
|
<strong>GPS Time (gps_us):</strong>
|
|
<ul style="margin: 10px 0 0 20px;">
|
|
<li>UTC time from GPS satellites</li>
|
|
<li>Used for correlation with iperf2 and other systems</li>
|
|
<li>Can have small adjustments as GPS sync improves</li>
|
|
<li>Example: Absolute timestamp for event correlation</li>
|
|
</ul>
|
|
</div>
|
|
</div>
|
|
|
|
<div class="section">
|
|
<h2>Additional Resources</h2>
|
|
<ul style="margin: 15px 0 0 20px;">
|
|
<li><a href="https://docs.espressif.com/projects/esp-idf/en/latest/esp32c5/get-started/" target="_blank">ESP-IDF Getting Started Guide</a></li>
|
|
<li><a href="https://docs.espressif.com/projects/esp-dev-kits/en/latest/esp32c5/esp32-c5-devkitc-1/user_guide.html" target="_blank">ESP32-C5-DevKitC-1 User Guide</a></li>
|
|
<li><a href="https://www.u-blox.com/en/product/neo-6-series" target="_blank">u-blox NEO-6 GPS Module Documentation</a></li>
|
|
<li><a href="https://sourceforge.net/projects/iperf2/" target="_blank">iperf2 Documentation</a></li>
|
|
</ul>
|
|
</div>
|
|
|
|
<footer>
|
|
<p><strong>ESP32-C5 GPS Synchronization Guide</strong></p>
|
|
<p>For WiFi Collapse Detection and iperf2 Latency Correlation</p>
|
|
<p>December 2025</p>
|
|
</footer>
|
|
</body>
|
|
</html> |