From e2d713f8c487cb844d151018eaf3da9f2c25eab5 Mon Sep 17 00:00:00 2001
From: nick <coachward0742@gmail.com>
Date: Mon, 15 Jun 2026 09:59:21 -0600
Subject: [PATCH] docs: add M9N GPS module plan

---
 docs/HARDWARE.md          |  4 +++
 docs/dashboard-esp32s3.md |  4 +++
 docs/gps-m9n.md           | 52 +++++++++++++++++++++++++++++++++++++++
 docs/project-state.md     |  4 +++
 docs/roadmap.md           |  4 +++
 5 files changed, 68 insertions(+)
 create mode 100644 docs/gps-m9n.md

diff --git a/docs/HARDWARE.md b/docs/HARDWARE.md
index 72bcbc7..7276475 100644
--- a/docs/HARDWARE.md
+++ b/docs/HARDWARE.md
@@ -235,3 +235,7 @@ Important guardrails:
 - Confirm relay polarity/state behavior.
 - Confirm available GPIO for DS18B20 and any optional OLED/status hardware.
 - Treat the LilyGO board as the controller, not the high-current load path.
+
+## M9N GPS Module
+
+The dashboard enclosure will include an M9N GPS module connected to the ESP32-S3 dashboard over UART. It will provide GPS fix status, satellite count, position, speed, and UTC time. Future work will use GPS time/location for automatic timezone and DST handling.
diff --git a/docs/dashboard-esp32s3.md b/docs/dashboard-esp32s3.md
index b4a7cd3..e48c63a 100644
--- a/docs/dashboard-esp32s3.md
+++ b/docs/dashboard-esp32s3.md
@@ -291,3 +291,7 @@ Each temperature sensor supports optional high-temperature alerting:
 - `high_alert`
 
 When enabled and the live sensor temperature exceeds the configured threshold, the Cargo ESP includes `high_alert: true` for that sensor in `/api/v1/status`. The ESP32-S3 dashboard colors the affected grouped temperature tile red if any sensor in that displayed group is in alert.
+
+## M9N GPS Module
+
+The dashboard enclosure will include an M9N GPS module connected to the ESP32-S3 dashboard over UART. It will provide GPS fix status, satellite count, position, speed, and UTC time. Future work will use GPS time/location for automatic timezone and DST handling.
diff --git a/docs/gps-m9n.md b/docs/gps-m9n.md
new file mode 100644
index 0000000..faad4dd
--- /dev/null
+++ b/docs/gps-m9n.md
@@ -0,0 +1,52 @@
+# M9N GPS Module Plan
+
+## Role
+
+The M9N GPS module will live in the dashboard enclosure and provide:
+
+- GPS position
+- GPS speed
+- Satellite/fix status
+- UTC time
+- Future automatic timezone/DST support
+- Optional GPS fallback speed display
+
+## Location
+
+Preferred mounting location:
+
+- Inside the top dashboard enclosure
+- Under the windshield
+- Near the ESP32-S3 dashboard display
+
+This should provide a clean enough sky view for normal vehicle GPS use.
+
+## Wiring
+
+Planned connection to dashboard ESP32-S3:
+
+- GPS TX -> ESP32 UART RX
+- GPS RX -> ESP32 UART TX, optional
+- GPS VCC -> 3.3V or 5V depending on module board
+- GPS GND -> dashboard ground
+
+PPS is optional and not required for v1.
+
+## V1 Data Goals
+
+Initial GPS fields:
+
+- Fix valid
+- Satellite count
+- Latitude
+- Longitude
+- Speed
+- UTC time
+
+## Future Features
+
+- Automatic timezone lookup
+- Automatic DST handling
+- Trip logging
+- GPS-based speed fallback
+- GPS diagnostics screen
diff --git a/docs/project-state.md b/docs/project-state.md
index 78781e7..58e3606 100644
--- a/docs/project-state.md
+++ b/docs/project-state.md
@@ -358,3 +358,7 @@ Each temperature sensor supports optional high-temperature alerting:
 - `high_alert`
 
 When enabled and the live sensor temperature exceeds the configured threshold, the Cargo ESP includes `high_alert: true` for that sensor in `/api/v1/status`. The ESP32-S3 dashboard colors the affected grouped temperature tile red if any sensor in that displayed group is in alert.
+
+## M9N GPS Module
+
+The dashboard enclosure will include an M9N GPS module connected to the ESP32-S3 dashboard over UART. It will provide GPS fix status, satellite count, position, speed, and UTC time. Future work will use GPS time/location for automatic timezone and DST handling.
diff --git a/docs/roadmap.md b/docs/roadmap.md
index 4589c0f..22ced84 100644
--- a/docs/roadmap.md
+++ b/docs/roadmap.md
@@ -188,3 +188,7 @@ Next Dashboard Milestones:
 - OBD-II integration
 - CAN integration
 - BNO085/BNO086 off-road attitude display
+
+## M9N GPS Module
+
+The dashboard enclosure will include an M9N GPS module connected to the ESP32-S3 dashboard over UART. It will provide GPS fix status, satellite count, position, speed, and UTC time. Future work will use GPS time/location for automatic timezone and DST handling.