Add Pac-Man power-on flow and document Odin integration

- Add a four-second arcade-style boot sequence followed by the
  Character / Nickname introduction.
- Separate cabinet power-on from RFID credit and player Start.
- Add operator Power on control and cabinet power-state reporting.
- Prevent repeated power commands from restarting boot or gameplay.
- Ignore RFID scans received before the cabinet is ready.
- Add power-state, RFID, controller, and GPIO feedback regression tests.

- Expand the master walkthrough with export, packaging, file transfer,
  fresh-Pi setup, RFID compilation, and end-to-end testing instructions.
- Correct tester hardware documentation: BCM23/J20 drives an LED;
  physical buttons connect through a separate I2C1 input board.
- Document operator-triggered power-on as the current test workflow
  and retain the temporary 2.4 configuration compatibility notes.
- Record successful physical testing of power-on, RFID credit,
  and player Start.

- Add an Odin integration README describing the proposed Rust/NATS
  bridge, shared messages, Flutter GM interface, autopilot sequencing,
  hardware ownership, and Starfish SSH-management role.
- Define migration milestones and information needed from the
  framework owner; link the integration guide from the root README.

Validation: 69 controller tests, 10 GPIO tests, Pac-Man power/RFID
checks, managed-cabinet lifecycle checks, and visual screen inspection.

tests/gpio/test_feedback.py

@@ -39,6 +39,8 @@ class FeedbackTests(unittest.TestCase):
         self.assertFalse(monitor.snapshot()['devices'][1]['value'])
         now[0]+=7
         self.assertGreater(monitor.snapshot()['devices'][0]['age_ms'],6000)
+        self.assertGreater(monitor.snapshot()['events'][0]['age_ms'],6000)
+        self.assertNotIn('stamp',monitor.snapshot()['events'][0])
         pin=monitor.inputs[0][1];monitor.close();outputs.close();self.assertTrue(pin.closed)
     def test_rfid_requires_helper(self):
         outputs=bridge.Outputs(Pin,'test',[25])

tests/pcb/check_pacman_managed_power.gd

@@ -0,0 +1,26 @@
+extends SceneTree
+func _initialize() -> void: call_deferred("run")
+func run() -> void:
+	var agent = load("res://tests/pcb/power_agent.gd").new()
+	root.add_child(agent)
+	agent.session = "test"
+	agent.boot = "test"
+	agent.cabinet = load("res://data/cabinets/cabinet_01.tres")
+	await agent.execute({"id": "prepare", "session": "test", "type": "prepare", "game": "pacman", "game_config": {"power_on_device": "cab1_btn_ylw", "rfid_credit_device": "cab1_rfid1"}})
+	assert(agent.phase == "powered_off")
+	assert(agent.outcomes.prepare.ok)
+	agent.game.set_physics_process(false)
+	await agent.execute({"id": "power", "session": "test", "type": "power_on"})
+	assert(agent.phase == "booting" and agent.outcomes.power.ok)
+	agent.game._physics_process(2.0)
+	await agent.execute({"id": "power", "session": "test", "type": "power_on"})
+	assert(agent.game.boot_elapsed == 2.0, "Duplicate commands must not restart boot")
+	agent.game._physics_process(2.0)
+	assert(agent.phase == "ready")
+	assert(agent.reports.any(func(r): return r.get("event") == "power_ready"))
+	await agent.execute({"id": "reset", "session": "test", "type": "reset"})
+	assert(agent.phase == "idle" and agent.game == null)
+	agent.queue_free()
+	await process_frame
+	print("MANAGED PACMAN POWER: PASS")
+	quit()

tests/pcb/check_pacman_managed_power.gd.uid

@@ -0,0 +1 @@
+uid://mofjts008nr7

tests/pcb/check_pacman_power.gd

@@ -0,0 +1,40 @@
+extends SceneTree
+var failures := 0
+func check(ok: bool, message: String) -> void:
+	if not ok:
+		failures += 1
+		push_error(message)
+func packet(id: String, kind := "input", device := "cab1_btn_ylw", value: Variant = true, age := 0) -> Dictionary:
+	return {"fresh": true, "events": [{"id": id, "kind": kind, "device": device, "value": value, "age_ms": age}], "devices": [{"id": device, "kind": kind, "value": false if kind == "input" else value, "age_ms": 0}]}
+func _initialize() -> void: call_deferred("run")
+func run() -> void:
+	var game = load("res://games/pacman/pacman.gd").new()
+	root.add_child(game)
+	game.set_physics_process(false)
+	game.configure({"power_on_device": "cab1_btn_ylw", "rfid_credit_device": "cab1_rfid1"})
+	check(game.power_state == "off" and not game.start_game(), "Prepared cabinet waits for power")
+	game.receive_device_feedback(packet("old"))
+	game.receive_device_feedback(packet("stale", "input", "cab1_btn_ylw", true, 5000))
+	game.receive_device_feedback(packet("wrong", "input", "other"))
+	game.receive_device_feedback(packet("early-card", "rfid", "cab1_rfid1", "12345678"))
+	check(game.power_state == "off" and game.credits == 0, "Historical/stale/wrong inputs and early cards are ignored")
+	game.receive_device_feedback(packet("tap"))
+	check(game.power_state == "booting", "A quick press released before polling still powers on")
+	check(not game.power_on() and not game.start_game(), "Boot cannot be restarted or skipped")
+	game._physics_process(3.99)
+	game.receive_device_feedback(packet("boot-card", "rfid", "cab1_rfid1", "12345678"))
+	check(game.power_state == "booting" and game.credits == 0, "Full four-second boot gates RFID")
+	game._physics_process(0.02)
+	check(game.power_state == "ready" and game.model.state == "idle", "Boot enters character intro, not gameplay")
+	game.receive_device_feedback(packet("boot-card", "rfid", "cab1_rfid1", "12345678"))
+	check(game.credits == 0, "First post-boot snapshot discards buffered scans")
+	game.receive_device_feedback(packet("new-card", "rfid", "cab1_rfid1", "12345678"))
+	check(game.credits == 1 and game.start_game(), "New scan then Start begins play")
+	game.receive_device_feedback(packet("playing-press"))
+	check(game.is_running and game.power_state == "ready", "Button during play cannot restart the cabinet")
+	game.power_off()
+	check(not game.is_running and game.credits == 0 and not game.start_game(), "Power off clears gameplay and credits")
+	game.queue_free()
+	await process_frame
+	print("PACMAN POWER: ", "PASS" if failures == 0 else "FAIL")
+	quit(1 if failures else 0)

tests/pcb/check_pacman_power.gd.uid

@@ -0,0 +1 @@
+uid://u60u4vs3he40

tests/pcb/check_rfid_credit.gd

@@ -12,6 +12,8 @@ func run() -> void:
 	var game = load("res://games/pacman/pacman.gd").new()
 	root.add_child(game)
 	game.configure({"rfid_credit_device": "cab1_rfid1", "rfid_allowed_uids": ["1234ABCD"]})
+	game.set_physics_process(false)
+	game._physics_process(4.0)
 	check(not game.start_game(), "Start must require a credit")
 	game.receive_device_feedback({})
 	game.receive_device_feedback(sample("old"))
@@ -35,6 +37,7 @@ func run() -> void:
 	game.receive_device_feedback(sample("new-scan"))
 	check(game.credits == 1, "New scan works after reset")
 	game.configure({})
+	game._physics_process(4.0)
 	check(game.start_game(), "Ordinary non-RFID Pac-Man remains free start")
 	game.queue_free()
 	await process_frame

tests/pcb/check_rfid_credit.gd.uid

@@ -0,0 +1 @@
+uid://djqv118y4dxxd

tests/pcb/power_agent.gd

@@ -0,0 +1,3 @@
+extends "res://core/network/managed_cabinet.gd"
+func _ready() -> void: pass
+func _process(_delta: float) -> void: pass

tests/pcb/power_agent.gd.uid

@@ -0,0 +1 @@
+uid://bt644lr2kyehf

tests/pcb/render_pacman_power.gd

@@ -0,0 +1,17 @@
+extends SceneTree
+func _initialize() -> void: call_deferred("run")
+func run() -> void:
+	var game = load("res://games/pacman/pacman.gd").new()
+	root.add_child(game)
+	game.set_physics_process(false)
+	game.configure({"power_on_device": "cab1_btn_ylw", "rfid_credit_device": "cab1_rfid1"})
+	for state in ["off", "booting", "ready"]:
+		game.view.power_state = state
+		game.view.startup_time = 1.0 if state == "booting" else 9.0
+		await process_frame
+		await process_frame
+		await RenderingServer.frame_post_draw
+		root.get_texture().get_image().save_png(OS.get_environment("TEMP").path_join("pacman-power-" + state + ".png"))
+	game.queue_free()
+	await process_frame
+	quit()

tests/pcb/render_pacman_power.gd.uid

@@ -0,0 +1 @@
+uid://b72d387gge7x7

tests/room_network/test_objectives.py

@@ -65,14 +65,30 @@ class ObjectiveTests(unittest.TestCase):
         self.fleet=test_fleet.server.Fleet(':memory:',self.catalog,lambda:self.now)
         self.poll('cabinet_01')
         room=self.fleet.rooms['cabinet_01']
-        room.features=['assignment_config_v1','rfid_credit_v1']
+        room.features=['assignment_config_v1','rfid_credit_v1','pacman_power_v1']
         room.gpio='real'
         self.fleet.operator('prepare_scenario', {'scenario':'pacman_rfid_credit_test'})
-        command=self.poll('cabinet_01')['commands'][0]
+        command=room.poll(dict(cabinet='cabinet_01',protocol=2,boot='cabinet_01',features=room.features,gpio='real',reports=[]))['commands'][0]
         self.assertEqual(command['game_config']['rfid_credit_device'],'cab1_rfid1')
         self.assertEqual(command['type'],'prepare')
-        self.poll('cabinet_01',[dict(kind='ack',id=command['id'],session=command['session'],ok=True)])
+        room.ack(dict(id=command['id'],ok=True))
+        self.assertEqual(room.state['phase'],'powered_off')
+        room.event(dict(id='power',event='power_booting'))
+        self.assertEqual(room.state['phase'],'booting')
+        room.event(dict(id='booted',event='power_ready'))
         self.assertEqual(room.state['phase'],'ready')
         self.assertFalse(any(c['type'] in ('output','reward','start') for c in room.state['commands']))
         self.poll('cabinet_01',[dict(kind='event',id='physical-start',session=command['session'],event='started')])
         self.assertEqual(room.state['phase'],'playing')
+
+    def test_power_validation(self):
+        room=self.fleet.rooms['cabinet_01']
+        room.gpio='real'
+        self.catalog['cabinets']['cabinet_01']['devices']=[dict(id='button',kind='input')]
+        item=dict(cabinet='cabinet_01',game='pacman',game_config=dict(power_on_device='button'))
+        with self.assertRaisesRegex(ValueError,'2.4'): self.fleet.validate_assignment(item)
+        room.features.append('pacman_power_v1')
+        self.fleet.validate_assignment(item)
+        for value in ['missing',True,17]:
+            with self.assertRaises(ValueError): self.fleet.validate_assignment(dict(item,game_config=dict(power_on_device=value)))
+        with self.assertRaises(ValueError): self.fleet.validate_assignment(dict(item,activate_after_win='cabinet_02'))

tests/room_network/test_power.py

@@ -0,0 +1,35 @@
+import unittest
+from test_room import server
+
+class PowerTests(unittest.TestCase):
+    def setUp(self):
+        self.room=server.Room(':memory:',lambda:100)
+        self.room.poll(dict(cabinet='cabinet_01',protocol=2,boot='a',features=['pacman_power_v1'],reports=[]))
+        self.room.state.update(game='pacman',game_config={'power_on_device':'button'},mappings={})
+    def tearDown(self): self.room.db.close()
+    def prepare(self):
+        self.room.operator('prepare')
+        command=self.room.state['commands'][-1]
+        self.room.ack(dict(id=command['id'],ok=True))
+    def test_operator_power_and_duplicate_events(self):
+        self.prepare()
+        self.assertEqual(self.room.state['phase'],'powered_off')
+        with self.assertRaises(ValueError): self.room.operator('start')
+        self.room.operator('power_on')
+        command=self.room.state['commands'][-1]
+        self.room.ack(dict(id=command['id'],ok=True))
+        self.assertEqual(self.room.state['phase'],'booting')
+        with self.assertRaises(ValueError): self.room.operator('start')
+        self.room.event(dict(id='booted',event='power_ready'))
+        self.assertEqual(self.room.state['phase'],'ready')
+        with self.assertRaises(ValueError): self.room.operator('power_on')
+        self.room.event(dict(id='booted',event='power_ready'))
+        self.assertEqual(self.room.state['phase'],'ready')
+    def test_dependency_autostart_waits_for_boot(self):
+        self.room.state.update(game_config={},auto_start=True)
+        self.prepare()
+        self.assertEqual(self.room.state['phase'],'booting')
+        self.assertFalse(any(c['type']=='start' for c in self.room.state['commands']))
+        self.room.event(dict(id='booted',event='power_ready'))
+        self.assertEqual(self.room.state['phase'],'starting')
+        self.assertEqual(sum(c['type']=='start' for c in self.room.state['commands']),1)