From 872997281fa0d07b6f7bc75caf2beda3ee48bd1c Mon Sep 17 00:00:00 2001
From: Mikkeli <mikkeli@novoyuuparosk.org>
Date: Mon, 12 Oct 2026 16:37:11 +0900
Subject: [PATCH] Mosquitto on the car Orin (localhost only); UPS read by
 orin-status Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
 Claude-Session: https://claude.ai/code/session_01DDwfd6Ki8UfG4hK6W5YpJz

---
 docs/BOM.md                    |  3 +++
 docs/impl/reports/MOSQUITTO.md | 48 ++++++++++++++++++++++++++++++++++
 2 files changed, 51 insertions(+)
 create mode 100644 docs/impl/reports/MOSQUITTO.md

diff --git a/docs/BOM.md b/docs/BOM.md
index 4512b80..05181d3 100644
--- a/docs/BOM.md
+++ b/docs/BOM.md
@@ -97,6 +97,9 @@ All ports are taken.
 - Ignition-off shutdown (not built yet): on input loss the battery current turns clearly negative (discharging). A small service watches the
   INA219, waits out a grace period longer than a crank (30–60 s), then runs `systemctl poweroff`, with low battery voltage as a hard backstop.
   The shunt value is unconfirmed; check the schematic before converting shunt mV to amps.
+- Read every second by svc-core's `orin-status` (read-only: register pointers only, chip left at defaults), published as
+  `yukart/host/ups_*`: pack voltage, current (+ charging), state, and a charge estimate. Waveshare's demo code
+  (`UPS_Power_Module_C.zip`, `ina219.py`) assumes a 0.01 Ω shunt and gives the sign, and maps 9.0–12.6 V linearly to 0–100 %.
 - No GPIO or shutdown signal on the module; the BOOT button may be needed to wake a battery that stopped outputting (FAQ).
 
 ## USB camera (IMX662, Sunplus UVC bridge)
diff --git a/docs/impl/reports/MOSQUITTO.md b/docs/impl/reports/MOSQUITTO.md
new file mode 100644
index 0000000..3d402b3
--- /dev/null
+++ b/docs/impl/reports/MOSQUITTO.md
@@ -0,0 +1,48 @@
+---
+type: report
+date: 2026-10-12
+---
+# Mosquitto: the bus on the car Orin
+
+The message bus (project-yukart decision 4), installed on the car unit.
+
+## Install
+
+```bash
+sudo apt-get install mosquitto mosquitto-clients     # 2.0.11-1ubuntu1.2 on Ubuntu 22.04
+```
+
+`/etc/mosquitto/conf.d/yukart.conf`:
+
+```
+# Yukart bus. Local only: displays reach it through svc-gw, never directly.
+listener 1883 127.0.0.1
+allow_anonymous true
+```
+
+`systemctl enable --now mosquitto`. It listens on `127.0.0.1:1883` only, so
+anonymous access is local access; nothing on the LAN, the tailnet or LTE can
+reach it.
+
+## Behaviour worth knowing
+
+- **Retained messages survive a reboot.** Ubuntu's `mosquitto.conf` sets
+  `persistence true` (`/var/lib/mosquitto/`), so after a reboot the broker
+  hands out the last values from before it. svc-gw therefore treats a value
+  known only from a retained copy as stale until a live one arrives.
+- Units that use the broker order themselves `After=mosquitto.service` and
+  nothing else, and reconnect by themselves when it restarts.
+- Startup tier 1 (project-yukart `docs/ORIN-RUNTIME.md`).
+
+## First use
+
+`orin-status` (svc-core) publishes the Orin's health on `yukart/host/<signal>`
+once a second; `svc-gw` subscribes and serves it to the tablet. Watching it:
+
+```bash
+mosquitto_sub -v -t 'yukart/#'
+```
+
+## Not checked yet
+
+- Throughput at raw CAN rates (`yukart/can/raw`, ~1000–3000 frames/s).