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/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.