From c18c25365828e81a9a72c6df37206e85598edcfa Mon Sep 17 00:00:00 2001
From: Cyd <cyd@falloutshelterarcade.com>
Date: Mon, 6 Jul 2026 13:35:37 -0500
Subject: [PATCH] RIO: document the board init handshake (test-mode + version)
 for vRIO

Decoded from L4RIO.CPP/HPP and verified byte-for-byte against a real
v4.2 board tap: CheckRequest 80 -> board must send TestModeChange ENTER
(8C 01 0D), self-test status stream (85 <status> <unit> <ck>), EXIT
(8C 00 0C), then answer VersionRequest 81 with 86 <maj> <min> <ck>.
Full command map 80-8C both directions, ACK/retransmit rules, and the
~1ms/byte 9600-baud pacing requirement. This is the implementation spec
for the user's vRIO (virtual RIO on COM1): its missing 8C packets are
exactly why the game logs 'RIO never came back from check request!'.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 emulator/RIO-NOTES.md | 38 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 38 insertions(+)

diff --git a/emulator/RIO-NOTES.md b/emulator/RIO-NOTES.md
index 3f94d3d..2978bd8 100644
--- a/emulator/RIO-NOTES.md
+++ b/emulator/RIO-NOTES.md
@@ -275,3 +275,41 @@ the entity gets a broken renderable and the sim eventually dereferences it.
 manually pointed at the selected arena's `VIDEO/GEO/<ARENA>` subdir). That is
 content/mission configuration, separate from the VPX protocol, the renderer,
 and the RIO — all of which now work.
+
+## Board init handshake — what a virtual RIO must implement (2026-07-06)
+
+The user's **vRIO** (virtual RIO on COM1) passed analog polling but the game
+still printed its init complaint. Root cause decoded from
+[L4RIO.CPP:901-975](../CODE/RP/MUNGA_L4/L4RIO.CPP) +
+[L4RIO.HPP:138-152](../CODE/RP/MUNGA_L4/L4RIO.HPP) and verified byte-for-byte
+against a real-board tap (riotap_arena.txt, fw v4.2):
+
+Command map (packet = cmd + body + 7-bit checksum `sum&0x7F`; FC=ACK FD=NAK
+FE=RESTART FF=IDLE): game→board `80` CheckRequest, `81` VersionRequest,
+`82` AnalogRequest, `83` ResetRequest, `84` LampRequest; board→game
+`85` CheckReply(status,unit; status: 0=BoardOk 1=BoardMissing 2=BoardBad
+3=LampBad 4/5/6=Restart/Abandon/FullBuffer counts), `86` VersionReply(maj,min),
+`87` AnalogReply(10 data bytes), `88`/`89` Button press/release,
+`8A`/`8B` Key press/release, `8C` TestModeChange(1=enter 0=exit).
+
+Init sequence (game side bombs with "RIO never came back from check request /
+test mode / version request!" if any step times out at 5s):
+
+1. game pulses DTR (assert 0.1s, drop, wait 1s) = hardware board reset
+2. game `80 00` → board `FC`
+3. **board `8C 01 0D` (TestModeChange ENTER)** ← the packet vRIO was missing;
+   game waits ≤5s for it, sets TestModeActive
+4. board self-test (~0.6s on the real board), streaming `85 <status> <unit>
+   <ck>` per subsystem (these are swallowed during test mode, not host events;
+   the bench board reports status=1 BoardMissing for units 08,10,11,18,19,1A,30)
+5. **board `8C 00 0C` (TestModeChange EXIT)** — game waits ≤5s
+6. game `81 01` → board `FC`, then **`86 04 02 0C` (VersionReply v4.2)**;
+   game loops until MajorRevision != 0xFF
+7. normal ops: `82 02` analog polls / button+key events. NOTE: the game sends
+   requests ONLY when `operational && !TestModeActive` — a board that enters
+   test mode and never exits mutes the game permanently.
+
+Every board packet is retransmitted until the game ACKs `FC` (within the
+TXMAXIDLE window; ~33ms with the patched EXE). Byte pacing at the 9600-baud
+wire rate (~1ms/byte) matters: vRIO blasting bytes back-to-back caused NAK/
+restart churn during init until the user added pacing.