yukart/project-yukart
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Rewrite reference docs as current state; record the style rule

Browse Source 
Reference, guidelines and plan documents describe what is and what will be.
Retirement stories, resolved-risk narration and against-the-alternative
argument moved out or were cut; reports keep that material.

What survives the cut is the mechanism that can bite again (driving side is a
country-level property) and the condition that would change a decision (a
permanently installed, car-powered panel), both stated generally.

Also removes a duplicated Japan section from a bad edit.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013kj58Jugkic783b8ZrtTVZ
This commit is contained in:
Mikkeli Matlock
2026-09-04 15:23:08 +09:00
parent 102cf38082
commit 574df1471c
4 changed files with 75 additions and 62 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/ARCHITECTURE.md
+32 -33
View File
@@ -91,8 +91,8 @@ rather than duplicated per client.
### Swappable providers
The same shape has now been chosen independently three times, so it is the
project's idiom rather than three coincidences:
A component with an expensive or not-yet-existing dependency puts it behind an
interface, with a trivial implementation alongside the real one:
| Component | Interface | Real | Trivial |
|---|---|---|---|
@@ -194,27 +194,22 @@ owns the boundary. For transports without IP — BT SPP, plain USB serial —
Because every display is a bus subscriber, adding, removing or swapping one
touches no acquisition code.
### Video out was dropped
### Directly-driven screens
An earlier revision had a second class: a screen driven directly by the Orin over
SPI/DP/HDMI, rendered by a local process. It is gone, and with it `app-hud`.
A screen driven over DP or HDMI is viable when it is **permanently installed and
powered by the car**. A dash-integrated panel qualifies: plug in DP and it is a
screen, and it adds a renderer without touching the contract, since the bus does
not care what draws it.
The reasoning, in order:
It is not viable for a removable display unit, which would need a second cable:
- **No connector-powered display exists.** DisplayPort's `DP_PWR` supplies 3.3 V
at 500 mA — and VESA-compliant cables deliberately leave it unconnected at the
sink. HDMI's +5 V pin gives 55 mA. A panel needs 5–15 W. So a directly-driven
screen always needs its own power feed, which is the cable the removable display
unit was meant to avoid.
- **DSI is not available.** The Orin Nano module carries DSI on SODIMM pins, but
the developer kit's carrier board does not break them out; DisplayPort is its
only display output. DSI would require a custom carrier board.
- **It bought nothing the browser-shaped path does not.** A data-only client on
one USB cable is simpler, and the display unit stays swappable.
| Supply | Available | A panel needs |
|---|---|---|
| DisplayPort `DP_PWR` | 3.3 V / 500 mA, and VESA cables leave it unconnected at the sink | 5–15 W |
| HDMI +5 V | 55 mA | |
Video out is what generated the enclosure, power and cabling complexity this
project started out trying to solve. Removing it removed the problem rather than
solving it.
DSI is unavailable on this carrier board — the module carries it on SODIMM pins,
but the developer kit does not break them out, so DSI needs a custom carrier.
## Navigation
@@ -252,8 +247,7 @@ Guidance is state, so it belongs on the bus: `yukart/nav/guidance` carries the
next manoeuvre, retained, and a display connecting mid-drive renders immediately.
Route *requests* are request/response and fit MQTT badly. Displays call the
Valhalla HTTP API through `telemetry-gw` instead of inventing a request/reply
topic pair. Recorded as decision 9.
Valhalla HTTP API through `svc-gw`. Recorded as decision 9.
### Map data is not source
@@ -287,18 +281,23 @@ checksum at both ends.
| **CJK labels** | MapLibre cannot ship Japanese glyph sets as SDF ranges — far too large. Set `localIdeographFontFamily` so the browser renders CJK from on-device fonts. Protomaps tiles also carry `name:en`, so romanised labels are an option. |
| **Addressing** | Japanese addresses are block-based, not street-based. Valhalla does not geocode at all, so destination search is a separate problem — do not assume a western geocoder transfers. |
### arm64 — resolved
### Verified on the Jetson
No longer a risk. Verified on `mikkeli-orin-nano-2` (L4T R36.4.7, JetPack 6) on
2026-09-04: `ghcr.io/valhalla/valhalla` publishes a `linux/arm64` manifest, the
image runs natively, and the full pipeline works end to end — config, timezones,
admins, tiles, and a served route.
`ghcr.io/valhalla/valhalla` publishes `linux/arm64` and runs natively on
L4T R36.4.7. Measured:
Measured: Shikoku, 49 MB PBF → 149 MB of routing tiles; Takamatsu → Matsuyama
routed in 157 km / 112 min with Japanese street names intact in the narrative.
| | |
|---|---|
| Shikoku PBF → routing tiles | 49 MB → 149 MB |
| Whole-Japan PBF | 2.4 GB |
| Admin DB, whole Japan | 17 MB |
| Timezone DB | 116 MB |
| Takamatsu → Matsuyama | 157 km, 112 min |
The server logs a benign `tiles.tar No such file or directory` warning and falls
back to the tile directory, which is the form decision 10 selected anyway.
Japanese street names survive intact in the route narrative.
The server logs `tiles.tar No such file or directory` at startup and falls back to
the tile directory, which is the form decision 10 selects. Not an error.
## Decisions
@@ -318,12 +317,12 @@ rewriting the document.
| 9 | Nav guidance published on the bus; route requests over HTTP via `telemetry-gw` | **Proposed** | 2026-09-03 |
| 10 | Map artifacts delivered by `rsync` over LAN only; Valhalla tiles kept as a directory, not a tar | Accepted | 2026-09-03 |
| 11 | Boot ordering is capture-first: acquisition reaches ready before serving or voice | Accepted | 2026-09-03 |
| 12 | The **tablet** owns the car's aux input; TTS crosses as chunked utterances, streaming-capable | Accepted | 2026-09-04 |
| 12 | The tablet owns the car's aux input; TTS crosses as chunked utterances, streaming-capable | Accepted | 2026-09-04 |
| 13 | Reasoning stays in the cloud — a local LLM does not fit beside the voice stack | Accepted | 2026-09-03 |
| 14 | Recordings are bounded with rotation | Accepted | 2026-09-04 |
| 15 | Boundary is two simplex channels — lossy stream down, acknowledged request/response up | Accepted | 2026-09-03 |
| 16 | Cloud links are outbound-initiated only; nothing calls in | Accepted | 2026-09-03 |
| 17 | `svc-gw` combines local hub and app gateway; no client may block the hub | Accepted | 2026-09-03 |
| 18 | Stubs publish the real topic and schema, never a fixture-specific one | Accepted | 2026-09-03 |
| 19 | Services mock themselves behind their own input interface; no separate stub implementations exist | Accepted | 2026-09-04 |
| 20 | Video out (Class A) dropped; every display is data-only. `app-hud` cancelled | Accepted | 2026-09-04 |
| 19 | A service mocks itself behind its own input interface; there is one implementation of each contract | Accepted | 2026-09-04 |
| 20 | Every display is data-only. Directly-driven screens are for permanently installed, car-powered panels only | Accepted | 2026-09-04 |