X Marks the Spot

X Marks the Spot is a phone-configured “adventure compass”:

• A mobile web app (phone) configures a trip and streams GPS location.
• A laptop-hosted server (Next.js + WebSockets) plans destinations (Gemini + Google Maps) and computes navigation guidance.
• An ESP32 device streams telemetry (IMU heading, temp/humidity, button) and receives commands (calibrate, pointer angle, display fields).

Quick start

1. Install deps:
   • npm install
2. Configure API keys (optional but recommended):
   • cp .env.example .env
   • Set GOOGLE_MAPS_API_KEY and GEMINI_API_KEY
   • Without keys, the server falls back to “demo” destinations and waypoint guidance.
3. Run locally:
   • npm run dev
4. Open on your phone (same Wi‑Fi as laptop):
   • http://<your-laptop-ip>:3000
5. (Optional) Run the simulated ESP32:
   • http://<your-laptop-ip>:3000/device-sim

HTTPS (for geolocation on mobile)

Some mobile browsers (notably iOS Safari) require HTTPS for reliable geolocation.

1. Generate a self-signed cert (includes localhost + 127.0.0.1 by default):
   • scripts/generate-dev-cert.sh --ip <your-laptop-ip>
2. Enable HTTPS:
   • XMS_HTTPS=1 XMS_HTTPS_KEY_PATH=certs/xms-dev.key.pem XMS_HTTPS_CERT_PATH=certs/xms-dev.cert.pem npm run dev
3. Open:
   • https://<your-laptop-ip>:3000

Note: self-signed certs may need to be installed/trusted on your phone; if that’s painful, consider using mkcert for a locally-trusted dev cert.

ESP32 connection

This repo supports two device connection topologies:

A) ESP32 connects to the server (default)

Have the ESP32 open a WebSocket to:

• ws://<your-laptop-ip>:3000/ws/device

B) Server connects outbound to ESP32 (relay mode)

Run the server with:

• npm run dev -- --esp32-url ws://<esp32-ip>:<port>

When --esp32-url is set, inbound connections to /ws/device are rejected (to avoid two active device sockets).

You can also set ESP32_URL in .env instead of passing --esp32-url.

Using calibration

1. Physically point the device toward true north (as best you can).
2. Tap Calibrate in the Trip screen.

Tests

• npm test

Docs

• docs/PRD.MD
• docs/IMPLEMENTATION_PLAN.MD
• docs/ESP32_OUTPUT_SCHEMA.MD