# 🛰️ GPS 轨迹采集系统：ESP32 + ATGM336H-5N + Android App

一套从硬件到 App 的完整 GPS 轨迹采集方案。ESP32 读取北斗/GPS 模块的 NMEA 数据，在 0.96 寸 OLED 上实时显示，同时通过 UDP 广播把定位数据发到局域网；手机 App 实时接收、入库、统计、导出 CSV，还能在高德地图上看轨迹。

架构上参照了我在 LBJ 列车信息采集系统 里验证过的那套"ESP32 广播 + App 自动发现"模式，这次做成了通用 GPS 采集工具。

✨ 功能特性

ESP32 固件端

  • NMEA 解析：TinyGPSPlus 解析 ATGM336H-5N 的 GGA / RMC / GSV 报文，拿到经纬度、速度、高度、卫星数、航向
  • OLED 实时显示：定位状态 + 卫星数 / 经纬度（WGS84，6 位小数）/ 北京时间 + 日期 / 速度 + 高度 / PPS 秒脉冲状态，中文界面用自绘点阵字库
  • UDP 广播推送：每秒把定位数据广播到 255.255.255.255:5001，任何设备打开就能收
  • 心跳自动发现：每 3 秒广播一次 ===GPS-HELLO===，App 不用手填 IP
  • SD 卡记录：SPI 挂载 microSD，原始 NMEA 与结构化数据落盘
  • SD 卡 Web 服务：局域网浏览器直接浏览 / 下载 SD 卡里的文件
  • WiFi 双模式：默认连 GPS-WiFi，连不上自动开热点 GPS-Track-5N；也支持串口命令 wifi <ssid> <password> 动态配置并写入 NVS

Android App

  • 实时监控：GPS 数据卡片（经纬度 / 速度 / 高度 / 卫星 / 定位状态）+ 原始报文日志流
  • 历史轨迹：Room 数据库存储，支持按时间筛选、导出 CSV、清空
  • 地图显示：接入高德地图 3D SDK，把采集点连成轨迹
  • 卫星视图：GSV 报文解析出的卫星星空图 + CN0 载噪比柱状图
  • 数据统计：今日 / 累计里程、定位率、采集点数
  • SD 卡浏览：通过 HTTP 拉取 ESP32 上 SD 卡的文件列表并下载
  • 深色模式：跟随系统，提供 values-night 配色
  • 前台服务：息屏也不断连，采集不中断

🧭 系统架构

ATGM336H-5N (GPS/北斗模块)
    │ UART 9600
    ▼
ESP32  (GPS_OLED 固件)
    │ ├─ OLED 本地显示
    │ ├─ SD 卡落盘 + Web 文件服务
    │ └─ WiFi: STA 连路由器 / AP 热点 GPS-Track-5N
    │         UDP 广播 255.255.255.255:5001
    ▼
Android App (GPS轨迹采集)
    ├─ 实时监控（GPS 卡片 + 原始日志）
    ├─ 历史轨迹（Room + 筛选 + 导出 CSV）
    ├─ 地图轨迹（高德 3D SDK）
    ├─ 卫星视图（星空图 + CN0）
    ├─ 数据统计（今日/累计/定位率）
    └─ 设置（端口 / 采集开关 / 信号源）

📡 通信协议（UDP 5001）

定位数据（每 1 秒）

[GPS]|yyyy-MM-dd HH:mm:ss|纬度|N|经度|E|速度km/h|高度m|卫星数|定位状态(1/0)|航向°

心跳（每 3 秒，供 App 自动发现设备）

===GPS-HELLO===|<ip>|5001
用 UDP 广播而不是 TCP 长连接，好处是一个 ESP32 可以被多台手机同时接收，且 App 侧实现极简 —— 绑个 DatagramSocket 就行，无需处理断线重连。

🔌 接线表（ATGM336H-5N → ESP32）

模块引脚ESP32说明
TXD (pin2)GPIO23GPS 数据输出 → ESP32 U2RX
RXD (pin3)GPIO22配置命令（只接收可不接）
1PPS (pin4)GPIO21秒脉冲（可选）
VCC (pin8)3V3模块供电 3.3V
GNDGND共地
VBAT (pin6)3V3 或 3V 电池可选，用于热启动

OLED（0.96" SSD1306，I2C）：SCL → GPIO26，SDA → GPIO27，VCC → 3V3，GND → GND

SD 卡（microSD，SPI）：CS → GPIO4，MOSI → GPIO5，MISO → GPIO19，SCK → GPIO18

卡座模块 VCC：带 LDO（AMS1117）的接 5V，裸卡座模块必须接 3V3。

四键 ADC 分压板：信号 → GPIO34，VCC → 3V3，GND → GND

⚠️ 踩坑记录一：不要用 GPIO12 / GPIO13 接 OLED
GPIO12 是 ESP32 的 strapping 引脚，上电时被 SCL 拉高会导致 flash 供电电压配置错误 → 无法启动、无法烧录。这也是为什么 OLED 放在 GPIO26/27。

⚠️ 踩坑记录二：四键按键不能用 GPIO25
GPIO25 属于 ADC2，WiFi 开启时 ADC2 不可用，按键会读不出值。改用 GPIO34（ADC1）。

📂 目录结构

ESP32+GPS+OLED/
├── GPS_OLED/                       # ESP32 主固件（PlatformIO）
│   ├── src/
│   │   ├── main.cpp                # NMEA 解析 + OLED 显示 + 主循环
│   │   ├── gps_net.cpp/.hpp        # WiFi 双模式 + UDP 广播 + 心跳
│   │   ├── sd_log.cpp/.hpp         # SD 卡挂载与日志落盘
│   │   ├── sd_server.cpp/.hpp      # SD 卡 HTTP 文件服务
│   │   └── chinese_font.h          # 自绘中文点阵字库
│   ├── platformio.ini              # 锁定 espressif32@5.3.0
│   └── README.md                   # 详细接线说明
├── SDTest/                         # SD 卡读写测试工程（独立烧录验证硬件）
├── GpsTrackApp/                    # Android App（Kotlin + Room + Material）
│   └── app/src/main/java/com/gps/trackcollector/
│       ├── net/                    # UdpReceiver + SignalSourceManager + SdFileClient
│       ├── data/                   # Room：Entity / Dao / Repository / Database
│       ├── parse/                  # [GPS] 报文 / GSV 卫星解析
│       ├── ui/                     # 主菜单 / 监控 / 历史 / 地图 / 卫星 / 统计 / 设置 / 关于
│       └── util/                   # CSV 导出 / 通知 / 偏好设置
├── apk/                            # 编译好的 APK（无需 Android Studio）
├── make_chinese_font.py            # 中文字库点阵生成脚本
└── README.md                       # 系统总览

🚀 使用流程

第一步：烧录 ESP32 固件

cd GPS_OLED
pio run -t upload
pio device monitor          # 115200
platformio.ini 里锁定了 espressif32@5.3.0（ESP-IDF 4.4 / Arduino 2.0.x），避免平台升级带来的库兼容问题。

第二步：配网

有两种方式：

  1. 串口命令（推荐，一次配好永久生效）

    wifi 你的SSID 你的密码

    配置写入 NVS，掉电不丢。

  2. 默认热点回退
    连不上预设 WiFi 时，设备自动开热点 GPS-Track-5N（密码 20260906），手机连上即可。

第三步：安装手机 App

到文章底部下载 gps-track-collector-v1.3.1.apk，安装时需允许"安装未知来源应用"。

第四步：开始采集

  1. 手机连到 ESP32 所在的同一个 WiFi（或直连它的热点）
  2. 打开 App → 实时监控，会自动发现设备并开始刷新
  3. 想存历史就打开采集开关，数据落在手机本地 Room 库
  4. 历史轨迹页可筛选、导出 CSV、清空
  5. 地图页看轨迹，卫星页看星空图与 CN0

重新编译（可选）

# ESP32 固件
cd GPS_OLED
pio run -t upload

# Android APK
$env:JAVA_HOME  = "C:\Program Files\Microsoft\jdk-17.0.20.8-hotspot"
$env:ANDROID_HOME = "C:\Android\Sdk"
cd GpsTrackApp
gradle assembleDebug
# 产物: app\build\outputs\apk\debug\app-debug.apk
编译 Android 需要在 gradle.properties 里填自己的高德地图 Key（AMAP_KEY=...），从 https://console.amap.com 申请。压缩包里已把 local.properties 剔除。

📥 下载

文件说明大小
gps-track-collector-v1.3.1.apk手机 App v1.3.1（debug 构建，含地图/卫星页）41.3 MB
gps-track-collector-v1.0-release.apk手机 App v1.0 release 构建（体积更小、无调试信息）41.3 MB
esp32-gps-oled-source-v1.0.zip完整源码（ESP32 固件 + SDTest + Android 工程，已剔除编译产物）118 KB

全部下载归档：https://unfamili.work/downloads/

⚠️ ATGM336H-5N 模块的厂商资料（使用手册、原理图、例程、uSTAR 上位机，约 200 MB）体积太大未随包上传，需要的话可以留言。

本项目用于嵌入式、GPS 定位与 Android 开发学习，仅供技术交流。