From b85a53e779bcf8325a3ac3585bc65ae5deb652c0 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 | 19 +++++++++++++++++++ docs/GUIDELINES.md | 16 ++++++++++++++++ docs/impl/plans/INITIAL.md | 30 ++++++++++++++++++++++++++++++ docs/impl/reports/.gitkeep | 0 4 files changed, 65 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..5880f3a --- /dev/null +++ b/README.md @@ -0,0 +1,19 @@ +--- +type: default +--- +# Telemetry gateway + +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. The network-facing surface for external display clients: +aggregates and rate-limits bus traffic on their behalf, and fronts the navigation +HTTP API so a display has one address to talk to. + +It is a bus subscriber. It never touches hardware and never transmits on CAN. + +- 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..ae50ac6 --- /dev/null +++ b/docs/GUIDELINES.md @@ -0,0 +1,16 @@ +--- +type: default +--- +# Gateway guidelines + +## 1. Read-only with respect to acquisition +- The gateway subscribes. It never opens a CAN socket, TX-capable or otherwise. +- `obd-poller` is the single writer on the bus. Nothing here changes that. + +## 2. Aggregate, do not relay +- A 500 kbps CAN bus produces far more traffic than a display can use or a USB + link should carry. Downsample and summarise here. +- If the gateway is only forwarding a topic unchanged, that client should have + subscribed to the broker directly instead. + +## 3. To be added diff --git a/docs/impl/plans/INITIAL.md b/docs/impl/plans/INITIAL.md new file mode 100644 index 0000000..64aa5cc --- /dev/null +++ b/docs/impl/plans/INITIAL.md @@ -0,0 +1,30 @@ +--- +type: default +--- +# Initial plan + +## The scope question, first + +This started as "aggregator and pusher to the tablet over USB". The pushing part +may not need to exist: over USB the tablet has an IP link via RNDIS, and the +architecture already says Class B devices reaching the bus over IP connect to the +broker directly. A Flutter MQTT client can talk to mosquitto with no hop in between. + +What does not go away: + +| Job | Why it needs a gateway | +|---|---| +| Aggregation | Raw CAN at 500 kbps must never reach a display; something has to downsample | +| Nav HTTP proxy | Route requests are request/response and fit MQTT badly | +| Static assets | Serving the PMTiles basemap to the display | +| Non-IP transports | BT SPP and plain serial for ESP32 clients have no broker access | + +So: build the aggregation and the HTTP surface. Do not build a telemetry relay for +clients that can already subscribe for themselves. + +## Order + +1. Static file serving for the basemap — smallest useful thing, unblocks the map. +2. Nav HTTP proxy to [svc-nav](gitea:yukart/svc-nav). +3. Aggregation and rate limiting, once there is real CAN traffic to aggregate. +4. Serial bridge, when an ESP32 client exists. diff --git a/docs/impl/reports/.gitkeep b/docs/impl/reports/.gitkeep new file mode 100644 index 0000000..e69de29