jeff/room_glitch
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source 
- 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.
This commit is contained in:
Jeff Luke committed 2026-10-17 18:47:26 -07:00
1 parent c1b2195834
commit 41ef12f954
27 files changed
+577 -48
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

docs/odin_integration/README.md
+173
View File
@@ -0,0 +1,173 @@
# Escape Gallery: Arcade Cabinet Integration
## Purpose and status
The target architecture combines the existing Godot arcade cabinet framework with the Rust room-control framework developed for Odin. Rust owns room sequencing, NATS carries control and state messages, and Flutter provides the game-master interface. Starfish is the proposed tool for managing Raspberry Pi SSH access.
**This document describes the intended integration, not a completed deployment.** The current arcade installation uses a Python room controller and browser operator interface. A physical Pac-Man test has successfully demonstrated operator power-on, the boot sequence, RFID credit, and player Start on a Raspberry Pi. The NATS bridge, Flutter cabinet controls, and shared autopilot integration remain to be implemented.
Glitch: the Dark Machine and Odin's Dilemma remain separate room implementations. Shared infrastructure, drivers, and messaging can be reused without mixing their puzzle rules, assets, device identities, or deployment configuration.
## Target system
```text
Staff laptops / tablets
|
v
Flutter GM interface
|
v
Rust room controller / autopilot
|
v
NATS messaging
|
v
Cabinet Rust integration (Godot GDExtension)
|
v
Godot cabinet application
| Game, graphics, sound, controls, credits and objectives
| Cabinet hardware interface
v
RFID / I2C inputs / LEDs / configured outputs
```
This diagram shows the logical control flow. The Flutter-to-controller transport and browser connection path must be confirmed against the owner's current framework. Hardware may run in a local service rather than inside the Godot process; each device must have one owner.
Starfish sits alongside this runtime architecture for SSH access management. It is not the game-message transport. Release packaging, service installation, update activation, and rollback need an agreed deployment workflow; SSH-key management alone does not provide those functions.
## Responsibilities
| Component | Intended responsibility |
| --- | --- |
| Godot cabinet application | Game selection, rendering, game audio, joystick/trackball/button mappings, boot presentation, credits, objectives, and game lifecycle. |
| Cabinet hardware layer | RFID and I2C drivers, input interpretation, configured output actions, and hardware status. |
| Rust Godot extension | NATS connectivity, generated message serialization, command validation and translation, state publication, and connection reporting. |
| Rust room controller / autopilot | Room sessions, puzzle sequencing, timed actions, dependencies between cabinets, room-wide effects, and GM overrides. |
| Flutter GM interface | Room layout, cabinet/device views, progress, diagnostics, and operator commands. |
| Shared message definitions and generator | Compatible command and state types for Rust, Dart, and any additional required languages. |
| Starfish | Proposed management of Pi SSH identities and access, subject to confirming its workflow. |
Room sequencing has one authoritative owner: the Rust controller. A cabinet owns execution of its assigned game and local interactions. For example, an accepted RFID scan can grant a local credit under the current assignment, while a completed game is reported to autopilot to determine which room puzzle activates next.
## Fit with the existing cabinet framework
The existing games remain in GDScript. The Rust extension provides methods and signals that GDScript can call or observe; it does not require rewriting gameplay in Rust or C#.
The current framework already supplies:
- Arcade games with configurable objectives and mapped player controls.
- Cabinet profiles, compatible-game assignments, and a visual PCB/device inventory.
- Pac-Man software power, boot, credit, Start, and completion behavior.
- A local Python GPIO bridge and Rust RFID helper.
- A managed-cabinet command/state integration point.
- An operator interface, room-layout authoring, and deployment tools useful during migration.
The existing HTTP integration can remain available for development and rollback while a NATS backend is introduced. Each deployed cabinet session must select one controlling backend; the Python controller and Rust autopilot must not independently issue competing assignments or advance the same room sequence.
The Godot editor remains useful for designing cabinets, defining devices, and authoring game objectives. An agreed export format should carry those definitions into the Rust/Flutter system so staff do not maintain conflicting copies manually. Existing room and cabinet visuals can inform the Flutter implementation, but the current HTML interface is not automatically reusable as Flutter widgets.
## Rust, NATS, and shared messages
A [godot-rust](https://godot-rust.github.io/book/) GDExtension is the proposed integration mechanism. It can use the existing Rust message types and NATS libraries while exposing a small cabinet API to Godot. If message serialization stays inside Rust, C# or GDScript message generation is not required for the initial integration.
The local Odin repository already contains:
- `msgs/*.geno` message definitions.
- Generator commands producing Rust types and Dart JSON models.
- Rust prop agents and puzzle controllers.
- An autopilot that observes puzzle state and schedules actions.
- Flutter services and controls for room operation.
**The inspected version uses MessagePack on prop-facing connections and JSON on game/UI-facing connections.** The current upstream schemas and wire formats must be confirmed before implementation. Sharing the name MessagePack is not enough: field order, optional values, enum encoding, and schema compatibility must match the generated implementation.
Networking and hardware operations must not block Godot's rendering/input loop. The extension should queue incoming work and deliver game-facing actions on the appropriate Godot thread. Build and export checks must cover the project's actual Godot version, Windows development builds, and Linux ARM64 cabinet builds.
### Proposed cabinet contract
The following are capabilities to agree on, not existing Odin message names:
| Direction | Capability examples |
| --- | --- |
| Controller to cabinet | Assign a compatible game, configure its objective/credit policy, power on, reset, request full state, invoke a configured hardware action. |
| Cabinet to controller | Identity/version, assignment, power/boot/play state, credit count, objective progress, win/loss, input changes, RFID observations, device faults. |
| Command result | Accepted, rejected, completed, or failed, with a command identifier and explanation. |
Commands and events should identify the room, cabinet, and active session. Define command IDs, expiry, duplicate handling, acknowledgement meaning, reconnect behavior, and state resynchronization before enabling sequencing or physical outputs.
Core NATS does not retain messages for offline subscribers. A one-time win event alone must not be the only record of completion. Agree on authoritative state snapshots, acknowledgement/retry behavior, and whether JetStream persistence is needed. Retries must not repeat credit grants or physical pulses.
## Hardware integration
The cabinet can present one hardware interface to gameplay even when the underlying drivers are split across services. Initially, the working Python bridge and Rust RFID helper can remain behind that interface. Individual drivers can then move to shared Rust components without changing each game's logic.
For the tester:
- J1 and J2 are the RFID reader connections; J1 currently grants Pac-Man credit.
- BCM23 / J20 is connected to an LED, **not the power button**.
- The physical buttons connect through a separate board on I2C1.
- Operator power-on is the current tested method until that input board is integrated.
The I2C board needs its model, address, channel mapping, polarity, and matching driver identified. Existing I2C support elsewhere in Odin does not establish compatibility with this particular board. The previously authored J20 button mapping is obsolete and must be corrected during configuration migration; BCM23 must not be configured as a button input.
Only one process may own each GPIO line, shared reader selector/reset arrangement, or hardware interface. Output commands should refer to configured device actions rather than allow arbitrary network pin writes. Define startup, disconnect, shutdown, and process-failure behavior for connected outputs.
## GM access and network layout
The required staff experience is a GM interface accessible from laptops and tablets on the building's local network. Flutter Web is the proposed browser target, subject to checking the current UI and its dependencies. A working Flutter desktop application does not by itself establish browser compatibility.
The master can host the Rust controller, NATS, and web-serving components while connecting to both the venue network and a private cabinet network. Staff devices access the GM interface; cabinets use the private network. The exact browser transport, authentication, NATS permissions, and required listening ports must be defined without opening general routing between those networks.
Keep these credentials distinct:
- SSH identities for installation and maintenance.
- NATS credentials and permissions for runtime messaging.
- GM authentication for staff operations.
## First integration milestone
Reproduce the already tested Pac-Man experience through the shared system:
1. Flutter assigns Pac-Man to Cabinet 1 and displays Waiting for power.
2. A GM Power on command reaches the cabinet through Rust/NATS.
3. Godot runs its four-second boot sequence and reports Ready.
4. A fresh accepted RFID scan grants one credit and plays the credit sound.
5. The player presses Start; the cabinet consumes the credit and reports Playing.
6. The player completes the configured objective; the cabinet reports completion.
7. Glitch autopilot activates the next configured puzzle or cabinet.
Acceptance includes reconnecting the network, restarting a cabinet, repeating commands, resetting a session, and verifying that no old scan, win, or output action is applied to a new session. Add the physical I2C button after its driver and mapping are confirmed.
## What is needed next
| Needed from the framework owner | Purpose |
| --- | --- |
| Current Odin/shared-framework repository, revision, and build instructions | Establish the actual integration baseline and private dependencies. |
| Message-generator source or installation instructions, plus current schemas | Generate compatible types and agree on cabinet command/state definitions. |
| NATS subject conventions, connection configuration, credentials/permissions, and persistence policy | Integrate cabinets with the existing messaging architecture. |
| Proposed Rust/Godot bridge API and implementation ownership | Decide who builds the extension, what GDScript calls, and how releases are maintained. |
| Hardware schematics, I2C board identity/address/channel mapping, and driver source | Integrate the tester's buttons and LED correctly. |
| Current Flutter build targets and browser-access expectations | Confirm laptop/iPad access and the required web transport. |
| Starfish enrollment/key-management workflow | Align Pi maintenance access with the owner's tooling. |
| Deployment conventions and ownership of room definitions | Agree on service names, release packaging, configuration generation, updates, and rollback. |
## Migration approach
1. Agree on the cabinet contract and hardware ownership with the framework owner.
2. Implement and test the Rust/Godot bridge using one Pac-Man cabinet.
3. Add matching Glitch controller logic and Flutter cabinet controls.
4. Transfer sequencing authority to autopilot for the test scenario.
5. Integrate the confirmed I2C driver and remaining cabinet devices.
6. Expand to additional games/cabinets, then port room-map and diagnostic views.
7. Adopt the agreed Starfish and release workflow while retaining a tested rollback path.
The existing working installation remains the reference until the new path passes the same physical tests. No deployment or runtime migration is performed by this document.
## References
- [godot-rust / GDExtension](https://godot-rust.github.io/book/)
- [NATS](https://nats.io/) and [Core NATS delivery behavior](https://docs.nats.io/learn/core-nats/)
- [MessagePack](https://msgpack.org/index.html)
- [Starfish repository supplied by the owner](https://github.com/jlyonsmith/starfish) — implementation not reviewed here.
- [Current arcade master setup walkthrough](../pacman_rfid_first_setup.md) — updated for operator power-on, RFID-only live inventory, and the corrected BCM23 LED / I2C button arrangement.
docs/pacman_rfid_first_setup.md
+57 -12
View File
@@ -2,7 +2,7 @@
This guide sets up **Glitch: the Dark Machine** with a master Pi hosting the operator webpage and Cabinet 1 running Pac-Man with the custom GPIO PCB. Follow the steps in order. Commands marked **PC**, **master**, or **cabinet** run on that machine. Replace `YOUR_USER` with the actual Pi login.
The supplied scenario is **Cabinet 1: Pac-Man RFID credit** (`pacman_rfid_credit_test`). It prepares Pac-Man with CREDIT 0. A new accepted scan on **J1 / cab1_rfid1** plays `games/pacman/audio/credit.wav` and changes the display to CREDIT 1. The player presses their mapped Start button, consuming the credit. It wins after one cleared board. It has no automatic win timer and no relay/motor rewards.
The supplied scenario is **Cabinet 1: Pac-Man RFID credit** (`pacman_rfid_credit_test`). It prepares Pac-Man in **Waiting for power**. Click the operator **Power on** button to run a four-second cosmetic ROM-check sequence followed by the Character / Nickname screen with CREDIT 0. A new accepted scan on **J1 / cab1_rfid1** plays `games/pacman/audio/credit.wav` and changes the display to CREDIT 1. The player presses their mapped Start button, consuming the credit. It wins after one cleared board. It has no automatic win timer and no relay/motor rewards.
The first test accepts any readable card. Credit is capped at one; scans during play do not bank credits. After a win/loss, reset and prepare the scenario again. The ordinary free-start Pac-Man assignment remains available separately.
@@ -72,14 +72,14 @@ This is the release-building part of the master walkthrough. Build everything fr
Open `D:\Projects\escape-gallery\room_glitch` in the project's Godot version (currently **4.7.2**). Save scenes and resources before running command-line exports. Check:
- Cabinet 1 has ID `cabinet_01`, and its PCB identifies J1 as `cab1_rfid1` and J2 as `cab1_rfid2`.
- `data/project_database.tres` includes **Cabinet 1: Pac-Man RFID credit**. Its assignment uses Pac-Man and `rfid_credit_device = cab1_rfid1`.
- `data/project_database.tres` includes **Cabinet 1: Pac-Man RFID credit**. Its assignment uses Pac-Man, `rfid_credit_device = cab1_rfid1`, and `power_on_device = cab1_btn_ylw`. The power setting and corresponding saved PCB entry are legacy metadata from the earlier button assumption; retain them temporarily for compatibility with the current 2.4 scenario validation. They do not describe the actual wiring. Do not include that legacy button in the bridge's `devices.json`. See the software-power notes at the end of this guide.
- The assignment has no output mappings for this initial reader test. `rfid_allowed_uids = []` accepts any readable card.
- The Linux preset is **ARM64**, with **Embed PCK disabled**. The existing Windows Desktop preset is x86_64.
- Export templates matching the editor version are installed (Editor > Manage Export Templates). An editor executable alone is not sufficient to export.
Use a release folder **outside the Godot project**. Do not export back into the project or mix old `setup/pi` exports with current source. In each preset's Resources tab, exclude the existing `setup/*` folder from the game export: it contains old exported artifacts and copied tools that do not belong inside a game PCK. Keep the actual `core`, `data`, `games`, `ui`, and runtime resources included. Do not add INIs, private keys, or SQLite files to the export's non-resource include filter.
The runtime for this scenario must advertise **arcade-cabinet-2.3** and `rfid_credit_v1`. Python files or a fresh catalog cannot add that feature to an old game PCK.
The runtime for this scenario must advertise **arcade-cabinet-2.4** and both `rfid_credit_v1` and `pacman_power_v1`. Python files or a fresh catalog cannot add that feature to an old game PCK.
### 3.2 Create a fresh release directory — Windows PowerShell
@@ -200,6 +200,35 @@ The resulting cabinet layout includes:
The extra controller files inside the cabinet bundle are harmless; do not start a second controller there. Continue with network setup in step 4, RFID build/devices.json in step 5, and the separate master/cabinet INIs in step 6. The `.sh` file, source repository, and Godot editor are not required on the cabinet.
### Optional exact copy commands from Windows
While both fresh Pis are still on venue Wi-Fi, record their Wi-Fi addresses with `hostname -I` on each Pi. Use those actual addresses here, not the later private Ethernet addresses. Keep the PowerShell release variables from section 3.2. Substitute your Pi usernames and current Wi-Fi IPs:
```powershell
$masterLogin = 'YOUR_MASTER_USER'
$masterHost = 'MASTER_WIFI_IP'
$cabinetLogin = 'YOUR_CABINET_USER'
$cabinetHost = 'CABINET_WIFI_IP'
tar -czf "$releaseDir\master.tar.gz" -C "$releaseDir\master" .
if ($LASTEXITCODE -ne 0) { throw 'Master archive failed.' }
scp "$releaseDir\master.tar.gz" "${masterLogin}@${masterHost}:master.tar.gz"
if ($LASTEXITCODE -ne 0) { throw 'Master copy failed.' }
scp "$releaseDir\$releaseName.tar.gz" "${cabinetLogin}@${cabinetHost}:$releaseName.tar.gz"
if ($LASTEXITCODE -ne 0) { throw 'Cabinet copy failed.' }
```
These SSH copies can use the Pi login passwords set in Imager; SSH key enrollment is not required for the first manual test. On first connection, verify the host fingerprint against the intended Pi before accepting it. Do not copy the operator token into an SSH password prompt.
On the **fresh master**, extract the master archive:
```bash
mkdir -p ~/arcade
tar -xzf ~/master.tar.gz -C ~/arcade
ls ~/arcade/tools/room_controller/server.py
```
On the **fresh cabinet**, use section 3.5's cabinet extraction commands. Compile and test the RFID helper in section 5 **before** section 4 disables cabinet Wi-Fi. After that, laptop access is to the master only; use the master to SSH to `192.168.77.11` if needed.
### 3.6 Preflight before calling the release ready
After completing steps 4–6, validate each machine without starting it:
@@ -220,7 +249,7 @@ python3 tools/launch/launch.py cabinet --config cabinet.ini --check
These checks validate configuration/dependencies/port availability. They do not prove card communication, display rendering, audio, or successful gameplay. Stop any existing stack first if the check reports its ports are occupied.
Use step 7's physical test as the acceptance gate: correct version, fresh J1 readings, CREDIT 0 -> scan/sound -> CREDIT 1 -> physical Start -> CREDIT 0, and no unintended outputs. Verify again after the reboot/startup test in step 9. Only then label the release ready for the room.
Use step 7's physical test as the acceptance gate: correct version, fresh J1 readings, Waiting for power -> operator Power on -> four-second boot -> CREDIT 0 -> scan/sound -> CREDIT 1 -> physical Start -> CREDIT 0, and no unintended outputs. Verify again after the reboot/startup test in step 9. Only then label the release ready for the room.
### 3.7 Optional fleet deployment: current RFID limitation
@@ -350,7 +379,11 @@ Create `~/arcade/devices.json` with this minimal RFID-only inventory:
]
```
J2 is visible for diagnostics but grants no credit in this scenario. This minimal inventory intentionally excludes existing buttons/outputs so the first test owns only the readers. Later you can extract the saved PCB catalog using `device_feedback.py` as documented in the GPIO guide.
J2 is visible for diagnostics but grants no credit in this scenario. **BCM23 / J20 is connected to an LED, not a button.** Do not wire a button there or configure it as an input. This test does not drive that LED or any other output; leave the output pin allowlist empty.
The tester's physical buttons connect through a separate input board on **I2C1**. Its model, I2C address, channel mapping, and matching driver still need to be confirmed before those buttons can control the game. For now, use operator **Power on**. The mapped arcade Start control is separate from this unimplemented I2C input board.
If following an older version of this guide, stop the cabinet stack, remove only the `cab1_btn_ylw` / J20 input entry from `devices.json`, and restart the stack. Keep the two RFID entries and preserve any unrelated site-specific devices. Do not regenerate the live inventory blindly from the saved PCB catalog: its legacy J20 button entry has not yet been migrated to the corrected hardware model.
## 6. Generate credentials and create the two INIs
@@ -425,14 +458,16 @@ python3 tools/launch/launch.py cabinet --config cabinet.ini
The cabinet launcher starts both the local GPIO bridge/reader helper and the game. Do not also start the standalone reader or another bridge. In a staff browser open `http://MASTER_VENUE_IP:8766` and log in with the **operator** token.
1. Confirm Cabinet 1 is online, reports `arcade-cabinet-2.3`, and GPIO is real.
1. Confirm Cabinet 1 is online, reports `arcade-cabinet-2.4`, and GPIO is real.
2. In Room control select **Cabinet 1: Pac-Man RFID credit** and prepare it. Reset an already active cabinet first if requested.
3. Wait for the game to show **SCAN CARD / CREDIT 0** and the operator Hardware view to receive fresh readings. Historical scans at preparation are deliberately ignored. Keep the card away until ready.
3. Wait for **Waiting for power** and fresh device readings. In **Cabinets**, select Cabinet 1 and click **Power on**. The operator should change to **Booting**, then **Ready** after four seconds; the cabinet shows the Character / Nickname introduction and **SCAN CARD / CREDIT 0**. Keep the card away until Ready; historical scans and scans during boot are discarded.
4. Press the cabinet Start button without a card: nothing should start.
5. Scan J1: hear the credit sound and see **CREDIT 1 / PRESS START**. Hold/re-scan the card: it must stay at one credit and not repeatedly sound for the same accepted credit.
6. Press the mapped Start button: Pac-Man starts and shows **CREDIT 0**. The operator changes to Playing. Operator Start is disabled for this scenario because the player must start it.
7. Scan during gameplay: no credit is banked. Clear one board to win. No physical reward is configured.
8. Reset/re-prepare to test again. Scanning J2 must never grant credit. Disconnecting the reader/bridge must not create credits; feedback becomes stale/error.
8. Operator Power on should be disabled during boot and play. Reset/re-prepare to return to Waiting for power and test again. Scanning J2 must never grant credit. Disconnecting the reader/bridge must not create credits; feedback becomes stale/error.
Use **Prepare assigned cabinets** for the named scenario, not the separate manual **Prepare game** action: ordinary Pac-Man boots automatically and does not wait for operator power-on.
The game uses the `arcade_start` input mapping. If the physical button is wrong, use the launcher Controls setup to map it and save, then return to managed mode. Keyboard/controller mapping is independent of the RFID reader.
@@ -451,7 +486,7 @@ score_to_win: 0
Replace the examples with your actual uppercase eight-character values. An empty array accepts any readable card. Changing this list does not write to the card. Keep a separate list of card labels and identifiers for your staff.
Save, re-export the controller catalog, and copy the updated catalog to the master. Restart the controller between sessions and re-prepare the scenario. For changes only to this assignment's allowlist/objective, the compatible 2.3 cabinet runtime accepts the new configuration without another game export. Game code, cabinet profiles, and new assets still require exporting the game.
Save, re-export the controller catalog, and copy the updated catalog to the master. Restart the controller between sessions and re-prepare the scenario. For changes only to this assignment's allowlist/objective, the compatible 2.4 cabinet runtime accepts the new configuration without another game export. Game code, cabinet profiles, and new assets still require exporting the game.
## 9. Enable startup after the manual test passes
@@ -463,7 +498,7 @@ python3 tools/launch/pi_service.py install --config "$HOME/arcade/cabinet.ini"
systemctl --user start arcade-cabinet.service
```
Stop the manually launched cabinet stack with Ctrl+C before installing. The installer captures the current desktop environment. The service intentionally has no boot enable target because the display must be ready first. For automatic start after desktop login, create `~/arcade/start-cabinet.sh`:
Stop the manually launched cabinet stack with Ctrl+C before installing. The installer captures the current desktop environment. The service intentionally has no boot enable target because the display must be ready first. For automatic start after desktop login, first run `mkdir -p ~/.config/autostart`, then create `~/arcade/start-cabinet.sh`:
```bash
#!/bin/sh
@@ -530,13 +565,23 @@ Run each command on the corresponding Pi. If startup is already managed by the d
| Reader unresponsive | Ribbon orientation, reader wiring/power, correct J1/J2 slots, no competing Odin process. |
| Blank/unprogrammed cards not reading | Check card technology; no card data-writing is required by this test. |
| Pin conflict on startup | Explicit blank output `pins`; RFID reserves BCM17/27/22/20 and SPI0. |
| Scenario rejected | Updated master catalog, cabinet 2.3 export, real GPIO, matching `cab1_rfid1` inventory. |
| Operator Power on is greyed out | Prepare the named RFID scenario using Prepare assigned cabinets; Cabinet 1 must be online, Waiting for power, and have no pending command. Check version 2.4 and preparation errors. |
| I2C buttons do nothing | The separate I2C input board is not integrated yet; use operator Power on and the mapped arcade Start control. |
| Scenario rejected | Updated master catalog, cabinet 2.4 export, real GPIO, matching `cab1_rfid1` inventory. |
| Live UID but no credit | Prepare this scenario, remove/re-present card after initial feedback, use J1, verify allowed UID. |
| Credit but no start | Verify `arcade_start` mapping and physical button. |
| Unauthorized | Operator token in browser; matching Cabinet 1 token on master/cabinet; check inherited environment. |
| Cabinet offline | Cabinet URL uses private master IP and `http://...:8766`; 8765 is only local GPIO. |
| Staff page inaccessible | Master venue address, venue client isolation/firewall, server bound to 0.0.0.0. |
Software regression tests cover credit gating, fresh versus historical/stale feedback, UID/reader filtering, duplicates, credit consumption, and non-RFID behavior. Physical reader/audio/controller/network behavior must still be checked on this installation. No Pi, GPIO, network, or live deployment was changed while preparing this guide.
Software regression tests cover credit gating, fresh versus historical/stale feedback, UID/reader filtering, duplicates, credit consumption, and non-RFID behavior. The operator power-on, RFID credit, and player Start flow has been physically confirmed by the user on the tester. Repeat the acceptance test for each fresh installation; the I2C input board and BCM23 LED control remain unverified and outside this test. No Pi, GPIO, network, or live deployment was changed while preparing this guide.
References: [Raspberry Pi networking/configuration](https://www.raspberrypi.com/documentation/computers/configuration.html), [Rust installation](https://doc.rust-lang.org/book/ch01-01-installation.html), [NXP MFRC522 supported card families](https://www.nxp.com/docs/en/data-sheet/MFRC522.pdf), [project GPIO guide](../tools/pi_gpio/README.md), [fleet deployment guide](../tools/deploy/README.md).
### Pac-Man software power and updates
This is a software state, not a mains relay. Operator **Power on** starts the cosmetic ROM-check sequence; it does not energize the BCM23 LED. Other games retain their existing startup behavior. The boot pattern is a visual recreation, not a checksum or hardware diagnostic.
**Temporary 2.4 compatibility:** keep `power_on_device = cab1_btn_ylw` in the scenario and its corresponding legacy input entry in the saved cabinet/catalog inventory for now. The current controller validates that reference, and the game uses its presence to remain in Waiting for power. Removing the setting makes Pac-Man boot immediately; removing only its catalog entry makes scenario validation fail. This is legacy configuration metadata, not permission to configure BCM23 as an input. The bridge's live `devices.json` must contain only the reader entries shown above for this test. A future change should introduce an explicit operator-only power mode and correct the saved PCB inventory together.
For a fresh release, export the Pi game, re-export the catalog, and package the controller and bridge from the same source version. A Windows game export is optional for PC testing. On an existing working 2.4 installation, removing the incorrect J20 entry from `devices.json` requires restarting the cabinet stack, not rebuilding the game or RFID helper. Preserve unrelated site-specific devices and settings. See section 3.8 for full software updates and rollback.