How niki-mardari/g-cacher works
G-Cacher combines a portable ESP32-S3 GNSS logger with a web platform for telemetry, mapping, saved locations, a GeoCache game, and 3D terrain visualization. The principal workflow runs from GNSS and sensor acquisition through device display, SD logging, and telemetry upload; the backend processes and stores data, then serves it to web views and returns GeoCache guidance to the device. Device and frontend excerpts support their local flows; backend behavior is only partly sampled, so uncertain endpoint wiring is omitted.
Main entry points: main.py FastAPI service · G_Cacher.ino Firmware loop · app.js Telemetry dashboard · geocache.js GeoCache game
Components 18
Device firmware
- Firmware loop
Firmware/src/G_Cacher/G_Cacher.ino - GNSS parsing
Firmware/src/G_Cacher/GnssManager.cpp - Sensor readings
Firmware/src/G_Cacher/SensorManager.cpp - Touch navigation
Firmware/src/G_Cacher/InputManager.cpp - Device menus
Firmware/src/G_Cacher/UiManager.cpp - SD logging
Firmware/src/G_Cacher/StorageManager.cpp - Network and saves
Firmware/src/G_Cacher/NetworkManager.cpp
API and persistence
- FastAPI service
Web/backend/app/main.py - PostgreSQL data
Web/database/init.sql
Web experiences
- Telemetry dashboard
Web/frontend/js/app.js - GeoCache game
Web/frontend/js/geocache.js - Saved locations
Web/frontend/js/saved-locations.js - 3D terrain viewer
Web/frontend/js/terrain.js
Other components
- Device and web user
- GNSS receiver
- Environmental sensors
- SD card
- Map tiles
Connections 24
- Device and web user → Touch navigation: touches controls
- Touch navigation → Firmware loop: changes menu or requests save
- GNSS receiver → GNSS parsing: sends NMEA
- GNSS parsing → Firmware loop: updates fix state
- Environmental sensors → Sensor readings: provides readings
- Sensor readings → Firmware loop: updates sensor state
- Firmware loop → Device menus: renders current state
- Firmware loop → SD logging: updates log
- SD logging → SD card: appends records
- Firmware loop → Network and saves: updates connectivity
- Network and saves → FastAPI service: posts telemetry and saved assets
- FastAPI service → Network and saves: returns GeoCache guidance
- FastAPI service → PostgreSQL data: reads and writes records
- Device and web user → Telemetry dashboard: views map and track
- Telemetry dashboard → FastAPI service: fetches dashboard data
- Telemetry dashboard → FastAPI service: posts simulated telemetry
- Telemetry dashboard → Map tiles: loads map tiles
- Device and web user → GeoCache game: views game
- GeoCache game → FastAPI service: fetches locations and telemetry
- GeoCache game → Map tiles: loads map tiles
- Device and web user → Saved locations: manages saved points
- Saved locations → FastAPI service: retrieves and updates assets
- Device and web user → 3D terrain viewer: inspects terrain points
- 3D terrain viewer → FastAPI service: loads recorded points