Software Implementation
Project Structure
your_project/
├── CMakeLists.txt
└── main/
├── CMakeLists.txt
├── main.c
├── gps_sync.h
└── gps_sync.c
gps_sync.h - Header File
#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);
gps_sync.c - Implementation
#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;
}
main.c - Example Usage
#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));
}
}
CMakeLists.txt
idf_component_register(SRCS "main.c" "gps_sync.c"
INCLUDE_DIRS ".")
Integration with iperf2
On Raspberry Pi 5 (iperf2 Server)
Your Pi is already GPS-synced. Run iperf2 with timestamps:
# 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
Correlation Analysis
Both systems now share GPS time. Example Python analysis:
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()
