Split README into a short front page and docs pages #115
Loading…
Reference in a new issue
No description provided.
Delete branch "docs/readme-split"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
The README had grown to 440 lines in a dense, aphoristic style. This rewrites it as a plain-English front page of about 150 lines, and moves the detail that needs intimate knowledge into
docs/:rpi-setup.md(moved from the repo root),updater.md,frame-bench.md,development.md, and a newentities.mdfor the entity-behaviour detail that didn't fit anywhere else.Every technical fact from the old README should still be present somewhere, checked against
updater/*.py,compose.yamland the tools scripts for exactness (ports, paths, env var names, endpoint routes). No facts were dropped and none invented.Tested:
ruff checkandruff format --checkpass (no Python changed). Confirmed by grep that nothing intests/references README text.Docs-only review. Found one meaning change worth fixing before merge, plus a couple of dropped facts and some leftover dense prose. Nothing else to flag — links all resolve, and the checkable claims (ports, paths, env vars, script behaviour) match compose.yaml, updater/*.py and manifest.json.
@ -45,0 +26,4 @@switched or set to a level. There's no acknowledgement: a command showsstraight away, then gives way to whatever the endpoint reports next, and isdropped if nothing answers within a second and a half. A node can ignore aremote command if someone in the van touched it in the last ten seconds, andThis says the node "says so" when refusing a remote command during the manual lockout. It doesn't: there's no ACK frame, and the refusal is only inferable from the origin/lockout fields on the endpoint's next state broadcast (see custom_components/campervan/lockout.py). docs/entities.md gets this right ("without saying so directly"). The old README also said "without saying so". Reword to match, e.g. "...and doesn't say so directly: the endpoint's own state frame shows who's holding it."
@ -52,2 +34,2 @@is in. An outage clears it: anything broadcast through the outage went unheard,and nothing on the bus repeats a mode or asks what the current one is.`SYS_MODE` sets the whole van's mode — normal, night, lights out, away,travel — from a select on the bridge device. Nothing acknowledges a modeThis sentence (also duplicated verbatim in docs/entities.md) stacks two em-dashes and three clauses in one ~40-word sentence — the dense style the rewrite was meant to remove elsewhere. Worth splitting, e.g.: "Nothing acknowledges a mode change. Each node decides for itself what it means. What's shown is the last mode broadcast — by Home Assistant or another node, with who asked for it — not necessarily the mode the van is actually in."
@ -289,0 +126,4 @@at all.- On a workstation with no CAN hardware, bring up a virtual bus by hand(`sudo ip link add dev vcan0 type vcan`, then `sudo ip link set up vcan0`)and give the config flow `vcan0`. A later `tools/frame-bench` run takes thatDropped instruction: the old README said a later
tools/frame-benchrun "takes that bus away with it, so bring it back the same way." This bullet (and docs/frame-bench.md) keeps the first half but drops the "bring it back" follow-up, so the reader isn't told they need to recreate vcan0 by hand again afterwards.@ -289,0 +128,4 @@(`sudo ip link add dev vcan0 type vcan`, then `sudo ip link set up vcan0`)and give the config flow `vcan0`. A later `tools/frame-bench` run takes thatbus away with it.- The Mosquitto broker that comes up alongside it is for Home Assistant's ownDropped fact: the old README's Mosquitto bullet ended with "so the MQTT integration wants
127.0.0.1on port1883with no credentials." That concrete setup instruction isn't in this bullet or anywhere in docs/. Worth keeping.Round 2 (commit
6a7b2d0) checked against round 1's findings.All four original findings are fixed correctly, matching the original pre-split wording:
The rewrite pass on entities.md/updater.md is a genuine improvement in style — no more stacked em-dash/clause sentences building to a point. Two things worth a look, both introduced by this pass:
@ -0,0 +88,4 @@kept apart because they mean opposite things: an unknown message type is theunversioned bus working as designed, but a decode failure is not.Beside them is a frame log, off by default, that writes every frame the PiThis changes the meaning, not just the style.
switch.py'sCampervanFrameLogdocstring says the switch is "Not restored on restart, so one left on cannot keep costing the display" — it resets to off on every Home Assistant restart, it isn't merely off as a starting default. The original wording ("off at every start") had that right; "off by default" reads like an ordinary default that could persist once changed, which it can't.@ -0,0 +96,4 @@Every node that announces itself also gets a firmware entity, on the samedevice as its other entities. The two versions it shows come from oppositeends: what's installed comes from the bus, from `SYS_ANNOUNCE`; what'savailable comes from the updater's cache, which only lists images whoseThis paragraph dropped a fact that was in the pre-split original: "...the updater only lists images whose bytes are already on disk, so a version showing there can be had now." That last clause (an offered update is actually ready to install, not just a known release string) isn't carried anywhere else in the rewrite. Worth restoring.
Round 3 check, focused on the two round-2 fixes and a fresh fact-drift pass over docs/entities.md and docs/updater.md.
Both round-2 fixes verified against code and correct:
CampervanFrameLogin custom_components/campervan/switch.py —log_framesstartsFalseand is never persisted.Went back through every paragraph of both files against the pre-split README (git show main:README.md) and the current code (lockout.py, commands.py's
ANSWER_ALLOWANCE = 1.5, firmware.py, update.py, sensor.py'supdate_drops_uplink, api.py'slatest_version). No further fact drift found — the wording moved but every claim (lockout attribute names, the 1.5s command timeout,wlan0hotspot, the manifest/cache mechanics,update_drops_uplinksemantics) still matches its source.Verdict: clean. Nothing left to fix — good to merge.
4acb8ab0173b1f75d6bbReviewed
1e2170donly (prior commits already settled).Facts all preserved: oscillator warning, txqueuelen line and the systemd-networkd persistence rationale are all still in docs/rpi-setup.md, and they read fine against the existing two-overlay example. README.md has no "Pi"/"Raspberry" left, and the Requirements/Running it sections flow naturally without the deleted section. Rest of README is untouched.
One trivial nit: README.md line 44 is now 81 characters (
as \NODE_BRIDGE` and sends a heartbeat every second. Its own device, node `0x01`,`) — one over the ~78-char wrap the rest of the paragraph uses, an artefact of "The Pi" → "Home Assistant" adding length. Worth reflowing that paragraph.@ -58,2 +43,2 @@which broadcasts nothing unless it is passed the word `SHUTDOWN`: a stray tapcannot produce a word, and an automation has to spell it out.Home Assistant is a node on the bus, not just a listener: it announces itselfas `NODE_BRIDGE` and sends a heartbeat every second. Its own device, node `0x01`,Line now 81 chars, one over this paragraph's ~78-char wrap — an artefact of "The Pi" → "Home Assistant" adding length. Reflow the paragraph.