Jeff Luke
c1b2195834
Operator hub - Introduce Escape Gallery branding and Glitch: the Dark Machine room views - Add cabinet illustrations, Pac-Man marquee/gameplay artwork, and waiting states - Add device feedback panels with RFID readings, input/output states, and stale status - Add logged operator hardware interventions with request deduplication Room and cabinet authoring - Add a visual custom-PCB connection editor with per-cabinet device inventory - Support device IDs, bindings, wiring notes, input polarity, and validation - Add physical-room label/dimension toggles and editable doorway annotations - Preserve doorway changes through undo, save, and revert - Expand cabinet profiles, room layout, and Glitch scenario resources Scenarios and gameplay - Add per-assignment game configuration and runtime feature validation - Add timed test wins and Frogger individual-home objectives - Add the three-cabinet timed/score/Frogger test scenario - Add Cabinet 1 Pac-Man RFID credits, credit sound, and CREDIT 0/1 display - Require physical Start after an accepted scan and prevent duplicate credits Pi hardware and deployment - Add GPIO feedback sampling and a separate multiplexed RFID helper - Validate reader pin ownership and input/output conflicts - Add SSH cabinet startup and Pi desktop-session service support - Add master packaging, site setup, SSH enrollment, and staged cabinet releases - Verify deployment manifests and support explicit activation/status/log commands Documentation and verification - Consolidate the root README around the current architecture and setup workflow - Add the complete master/Pi/RFID export and deployment walkthrough - Document network isolation, credentials, card identification, and rollback - Add PCB, room-editor, feedback, credit, deployment, and controller tests - Isolate protocol tests from designer-edited cabinet configurations Known limitations - RFID helper compilation and physical Pi commissioning remain unverified - Fleet provisioning does not yet configure RFID-only installations completely - Broader Pac-Man tests retain a ghost-capture assertion failure - Staged exports must be rebuilt and checked before deploying runtime 2.3
11 KiB
Master Pi deployment: first box test
This first implementation provides a terminal setup wizard, portable master software, versioned cabinet uploads, configuration generation and SSH service controls. The normal browser operator remains the game-master interface. There is not yet a browser provisioning wizard or automatic network reconfiguration.
It does not connect to any Pi until you explicitly run an enrollment/deployment command. It does not pulse GPIO, trigger a puzzle, reset controller mappings, or copy the development site's credentials. Use one spare cabinet first.
1. Prepare clean deployment packages on the development PC
From the project root (replace the release label for each build):
py -3 tools/deploy/deploy.py master-package --output D:/ArcadeMaster-test1
py -3 tools/deploy/deploy.py bundle --export setup/pi --output D:/arcade-test1.tar.gz --release test1
The output directory and bundle must not already exist. The master package is an explicit allowlist of Python/scripts, operator assets and catalog. The cabinet bundle contains the current ARM64 executable/PCK plus scripts and a checksum manifest. No live INIs, tokens, SQLite files, SSH keys or Odin files are copied. Package an export built from the same game/cabinet catalog: the packager validates ARM64/PCK headers, but cannot prove a PCK was exported from the matching source revision.
Copy ArcadeMaster-test1 and arcade-test1.tar.gz to the master Pi, for example under its desktop user's home. No Godot editor is needed on the master.
2. Network for the box
First confirm the physical arrangement: master Ethernet to the box's private switch, cabinet Ethernet to that switch, and master Wi-Fi (or a second Ethernet adapter) to the venue LAN. Do not also connect the private switch to the venue router. Cabinet Wi-Fi must not bypass the private network.
A plain switch does not supply DHCP. For the initial box test, manually configure unique static wired addresses through each Pi's desktop network settings. Choose a subnet that does not overlap the venue network; an example is master 192.168.77.1/24, cabinet 1 .11/24, cabinet 2 .12/24, cabinet 3 .13/24. Leave the private connection's gateway and DNS blank, and keep the master's default Internet route on its venue connection. Record the real addresses in setup below. A later installer can provide private DHCP reservations.
The deployment tool does not install a firewall or enforce network isolation. The master must not bridge the interfaces or enable IP forwarding/connection sharing. For an enforced deployment, apply a firewall policy that drops forwarding in both IPv4 and IPv6, permits cabinet controller traffic to the master on TCP 8766, and permits venue browsers to the operator port. This needs the actual interface/subnet information; do not blindly replace an existing firewall. Staff on an isolated guest Wi-Fi may not be allowed to reach the master.
You may test the software on the existing LAN first; that is not a closed cabinet network. The browser connects to http://MASTER_VENUE_IP:8766; cabinets use http://MASTER_PRIVATE_IP:8766. Game-master commands travel through the master. No direct staff-browser-to-cabinet route is required.
3. Pi prerequisites
Use Raspberry Pi OS 64-bit with a desktop on the cabinets. Enable SSH and desktop autologin for the same ordinary user who runs the game. The master needs Python 3 and the OpenSSH client; it can be headless after initial setup.
On the master, if the commands are missing:
sudo apt install python3 openssh-client
On cabinets using real GPIO, install dependencies before disconnecting Internet access:
sudo apt install python3-gpiozero python3-lgpio
The cabinet user needs GPIO device permission (normally the Raspberry Pi OS gpio group). The first test may use GPIO disabled. Do not guess MOSFET/NFC pins: enable only the BCM outputs already defined and wired for that cabinet. NFC input integration is separate from deployment.
4. Register the site on the master
From the copied master folder:
python3 tools/deploy/deploy.py setup
The wizard asks for the private controller URL, each cabinet's existing catalog ID, its address and SSH user, and GPIO settings. It generates distinct site credentials and configurations in ~/.local/share/arcade-master/, with private permissions. It never asks for or stores the Pi login password. Re-running setup edits entries and preserves tokens. Press Enter at the cabinet-ID prompt when finished.
For this release choose cabinet_01, cabinet_02, or cabinet_03, matching the existing exported hardware profiles. Arbitrary new IDs require a matching export/catalog; dynamic runtime profiles are not implemented yet. The GPIO controller ID must match the project's hardware action definitions, not merely a newly invented name.
To inspect/edit the inventory later, use inventory.json in that site directory and run python3 tools/deploy/deploy.py generate. Never rotate or hand out another cabinet's token accidentally. Changing an active site's master credentials/config requires a controller restart and matching cabinet reactivation. Do maintenance between sessions.
5. Enroll, check and upload ONE cabinet
python3 tools/deploy/deploy.py enroll cabinet_01
python3 tools/deploy/deploy.py preflight cabinet_01
python3 tools/deploy/deploy.py stage cabinet_01 --bundle ~/arcade-test1.tar.gz
Enrollment creates a dedicated master SSH key if none exists, asks you to verify the target host fingerprint, and uses ssh-copy-id with the cabinet's existing login. It preserves other authorized keys. The key has no passphrase so startup can be unattended; protect the master account and its site backup. Subsequent commands require the verified host key and key-based authentication without prompts.
Preflight reports architecture, Python version, GPIO-package availability, free space and whether the display helper has captured a desktop session. Uploads use SSH and verify an exact file allowlist and every SHA-256 checksum. Staging does not stop or start a game. An interrupted upload leaves the previous release untouched; rerun stage. Reusing a release ID with different contents is rejected.
6. Activate and initialize the desktop helper
Stop any manually launched game/bridge first. If the cabinet service is running, explicitly stop it between tests:
python3 tools/deploy/deploy.py stop cabinet_01
python3 tools/deploy/deploy.py activate cabinet_01 --release test1
Skip the stop command on a fresh cabinet with no service. Activation refuses to replace a running service and refuses to overwrite unrelated service files. It writes that cabinet's INI and installs the normal user service through SSH. The master/operator token is never sent to the cabinet. If registration fails, prior service files/config are restored.
On a fresh cabinet, log out and back into its desktop once after activation, or run this on its local desktop terminal:
python3 ~/.local/share/arcade-deploy/releases/test1/tools/launch/pi_service.py refresh-session
The desktop autostart helper refreshes this display environment at future logins. SSH cannot safely guess the active display. The first remote install therefore reports waiting for desktop readiness instead of pretending the game has started. No root process renders the game.
7. Start the master and verify
On the master, from its software folder:
python3 tools/deploy/deploy.py install-master
sudo loginctl enable-linger "$USER"
systemctl --user start arcade-master.service
python3 tools/deploy/deploy.py health
The installer enables the master user service, but does not start it until the start command. Lingering starts the master service at boot even without a desktop login. The master launcher tries to start the registered cabinet services and reports authenticated ONLINE status separately from SSH success. A cabinet must already have its display environment ready. If it logs in later, issue start below; startup has bounded waits, not an endless retry loop.
Open http://MASTER_VENUE_IP:8766 in a staff browser. Read the operator token from the master site's controller.ini; it is separate from SSH credentials and cabinet tokens. Existing scenario controls, overrides and hardware actions remain available in the operator page. Deployment does not automatically prepare a scenario or test a hardware output.
python3 tools/deploy/deploy.py start cabinet_01
python3 tools/deploy/deploy.py status cabinet_01
python3 tools/deploy/deploy.py logs cabinet_01
python3 tools/deploy/deploy.py health
To diagnose the master: journalctl --user -u arcade-master.service -n 60 --no-pager.
Updates, rollback and state
Use a new release label and stage it while the old game is running. Between sessions, stop the cabinet, activate the new release and start it. To roll back, stop it and activate the previous release label again. Previous releases are retained; no automatic cleanup deletes them. Reusing the same release for another cabinet identity on the same device overwrites only that release's generated INI after the service is stopped.
Game user data/control mappings stay in Godot's existing user-data directory. GPIO deduplication stays at ~/.local/state/arcade_gpio/requests.sqlite3. Cabinet logs are under ~/.local/state/arcade_cabinet/logs. The new master site has its own controller database under the site's state/; it does not silently import or overwrite the development controller database.
Back up the master site folder (inventory, tokens, SSH key and controller database) securely. After moving to a non-overlapping venue network, retain the private addresses and update the master venue connection/operator bookmark. This version does not reconfigure network interfaces automatically.
Box acceptance checklist
- One cabinet enrolls, stages and activates; a failed upload does not stop the existing game.
- A fresh desktop login produces display readiness and the game appears on the cabinet monitor.
- Operator sees the expected cabinet ONLINE and can prepare/start/reset the existing scenario.
- Existing manual progression/hardware controls still work through the master; only test a known wired output deliberately.
- Restart the master; it comes back without a login and cabinets reconnect without replaying a reward.
- Restart a cabinet; after desktop login, explicitly start it if the master's initial startup attempt has already passed.
- Verify staff can reach the operator and, once isolation is configured, cannot directly reach cabinet addresses.
- Repeat with remaining cabinets, then run the three-cabinet test.