project-yukart/docs/ARCHITECTURE.md

Architecture

The one rule

Everything is a bus participant. Acquisition services publish; displays, loggers and analysis tools subscribe. No service knows which display exists, and no display talks to hardware.

This is what lets the three display options coexist without forking the system, and what lets a service be restarted or replaced mid-drive without taking the rest down.

Shape

   CAN (can1) ──▶ can-bridge ──┐
   OBD-II      ──▶ obd-poller ─┤
   GNSS        ──▶ gnss        ├──▶  message bus  ──┬──▶ recorder (disk)
   camera      ──▶ vision*     ─┘                   ├──▶ hud (local video out)
                                                    └──▶ telemetry-gw ──▶ remote displays
                          * later phase, separate task

Services

Service	Responsibility	Transmits on CAN
can-bridge	Read SocketCAN frames, timestamp, publish raw	No
obd-poller	Active OBD-II PID request/response	Yes
gnss	gpsd client → position, speed, time fix	No
decoder	Raw frames → named signals via DBC	No
recorder	Persist raw + decoded sessions to disk	No
telemetry-gw	Serve external display clients	No
vision	Camera capture and on-device inference (later)	No

Each ships as a systemd unit. The host-level prerequisites they depend on (kernel modules, device permissions, gpsd) are the environment repo's job, not theirs.

CAN bus scope

Passive sniffing plus active OBD-II queries. OBD-II is a request/response protocol, so it necessarily transmits onto a 2008 car's bus. Constraints that follow:

• can-bridge runs listen-only and must never transmit.
• obd-poller is the single writer. No other service opens a TX-capable socket.
• Transmission is rate-limited and restricted to standard OBD-II diagnostic IDs.
• TX is a distinct, explicitly enabled mode — not the default state on boot.

Reverse-engineering of Z27AG-specific frame IDs proceeds purely from observed traffic; discovered signals are recorded as a DBC rather than as code.

Message bus

Proposed: MQTT (mosquitto) on the Jetson. Rationale:

• First-class client libraries on every display target — ESP32 (Arduino PubSubClient / ESP-IDF) and Android (Paho) — which is the deciding factor.
• Broker handles fan-out and retained "last known value", so a display that connects mid-drive immediately has state to render.
• Trivially inspectable with mosquitto_sub while debugging in a car.

Rejected: NNG/ZeroMQ (lower latency, no broker, but a poor ESP32 story and no retained values); DDS (capable, disproportionate).

Topics

yukart/can/raw            high-rate raw frames, not retained
yukart/vehicle/<signal>   decoded signals (rpm, speed, coolant, …), retained
yukart/gnss/fix           position/speed/time, retained
yukart/system/<service>   health and status, retained

Payloads: JSON for low-rate signals (readable, debuggable); compact binary or CBOR for can/raw, since a 500 kbps bus produces far more traffic than JSON should carry.

Topic names and payload schemas are a contract shared across repos — Android and ESP32 clients depend on them — so they are versioned in their own repo rather than duplicated per client.

Display contract

Three display paths, in two classes:

Class A — video out. A screen driven directly by the Orin over SPI/DP/HDMI. The renderer is a local process subscribing to the bus over loopback.

Class B — data only. The Orin sends no video, only data; the device renders itself.

Path	Transport	Notes
Android app	WiFi, or USB (RNDIS)	Full-featured client, richest UI
ESP32 + RLCD/e-ink	WiFi, or USB/BT serial	Low-rate, glanceable subset of signals

Class B devices reaching the bus over IP connect to the broker directly. For transports without IP (BT SPP, plain USB serial), telemetry-gw bridges serial ↔ bus rather than each device inventing its own protocol.

Because both classes are bus subscribers, adding, removing or swapping a display touches no acquisition code.

Decisions

Recorded here so fast-moving choices stay visible. Flip a row rather than rewriting the document.

#	Decision	Status	Date
1	Separate services over a message bus, not one process	Accepted	2026-08-14
2	Displays are bus subscribers; no display-specific logic upstream	Accepted	2026-08-14
3	Listen-only sniffing + active OBD-II, single writer	Accepted	2026-08-14
4	MQTT as the bus	Proposed	2026-08-14
5	Implementation language(s) per service	Open	—
6	Local logging first; off-board LTE telemetry deferred	Accepted	2026-08-14
7	Camera/AI inference is a later, separate task	Accepted	2026-08-14