From 570a8c541dc631460f21299d0e01ebe5eead36a1 Mon Sep 17 00:00:00 2001 From: Mikkeli Date: Thu, 3 Sep 2026 18:48:32 +0900 Subject: [PATCH] Scaffold repo: docs layout, guidelines and initial plan Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_013kj58Jugkic783b8ZrtTVZ --- README.md | 21 +++++++++++++++++++++ docs/GUIDELINES.md | 18 ++++++++++++++++++ docs/impl/plans/INITIAL.md | 32 ++++++++++++++++++++++++++++++++ docs/impl/reports/.gitkeep | 0 4 files changed, 71 insertions(+) create mode 100644 README.md create mode 100644 docs/GUIDELINES.md create mode 100644 docs/impl/plans/INITIAL.md create mode 100644 docs/impl/reports/.gitkeep diff --git a/README.md b/README.md new file mode 100644 index 0000000..4282de2 --- /dev/null +++ b/README.md @@ -0,0 +1,21 @@ +--- +type: default +--- +# Navigation service + +Part of **Project Yukart**, making an old 2008 Mitsubishi Z27AG a bit smarter with modern technologies. +This file serves as the minimalist portal to other docs + + +## What this repo is about + +Runs on the Orin. Answers routing questions and publishes turn-by-turn guidance +onto the message bus, so no display has to know where routes come from. + +Routing is served by a local Valhalla instance against artifacts built by +[tool-mapmint](gitea:yukart/tool-mapmint), which is the offline-capable default. +The provider is kept behind an interface so a cloud routing API can be swapped in +without touching anything downstream. + +- For implementation practice guidelines, refer to the [guidelines](docs/GUIDELINES.md); +- For implementation plans and history, refer to [them](docs/impl/); diff --git a/docs/GUIDELINES.md b/docs/GUIDELINES.md new file mode 100644 index 0000000..e946fe9 --- /dev/null +++ b/docs/GUIDELINES.md @@ -0,0 +1,18 @@ +--- +type: default +--- +# Navigation service guidelines + +## 1. Routing providers stay behind one interface +- Nothing outside the provider boundary may reference Valhalla types, Valhalla + URLs, or Valhalla's response shapes. +- A cloud provider (GCP or equivalent) must be addable without changes to the + bridge, the published topics, or any display. +- Local Valhalla is the default because it works with no signal; a cloud provider + is an option, never a dependency. + +## 2. Guidance is published, routes are requested +- Live guidance goes onto `yukart/nav/guidance`, retained. +- Route requests are request/response and are served over HTTP, not MQTT. + +## 3. To be added diff --git a/docs/impl/plans/INITIAL.md b/docs/impl/plans/INITIAL.md new file mode 100644 index 0000000..ae27a26 --- /dev/null +++ b/docs/impl/plans/INITIAL.md @@ -0,0 +1,32 @@ +--- +type: default +--- +# Initial plan + +## Scope + +Turn a GNSS fix plus a destination into guidance on the bus. Nothing about +rendering — that belongs to the display client. + +## Order + +1. Confirm Valhalla builds and runs on the Jetson (arm64). This is the one real + integration risk in the whole navigation workstream — upstream's arm64 + container story is unsettled. Do it before anything else. +2. Stand up Valhalla against artifacts from `tool-mapmint`, serving HTTP locally. +3. Define the routing provider interface, with Valhalla as the first implementation. +4. Bridge: subscribe to `yukart/gnss/fix`, publish `yukart/nav/guidance`. +5. Meili map matching over recorded sessions — see below. + +## Why map matching comes early + +Meili's `trace_attributes` snaps a recorded GNSS trace onto OSM and returns road +attribution along it: speed limit, road class, geometry. That is ground truth for +validating reverse-engineered CAN signals, which is otherwise guesswork. It is +worth having before any navigation UI exists. + +## Blocked on + +Live guidance needs a GNSS fix, which needs gpsd, which needs the SIM7600 brought +up in [orin-nano-env-setup](gitea:yukart/orin-nano-env-setup). Everything else here +can be built and validated against a replayed trace. diff --git a/docs/impl/reports/.gitkeep b/docs/impl/reports/.gitkeep new file mode 100644 index 0000000..e69de29