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
142 lines
8.1 KiB
Markdown
142 lines
8.1 KiB
Markdown
# Start the Arcade stack
|
||
|
||
To start the Pi applications automatically from the PC controller command, follow the [remote Pi startup guide](../../docs/remote_pi_start.md).
|
||
|
||
For the assigned internal operator/Cabinet 1–7 tokens and per-machine Godot CFG examples, see the [cabinet setup guide](../../docs/cabinet_setup.md).
|
||
|
||
One launcher starts the needed processes, waits for services to respond, saves logs, and stops its children when you press Ctrl+C. It runs on Windows and Linux/Pi (and supports controller-only use on macOS).
|
||
|
||
| Mode | Starts |
|
||
| --- | --- |
|
||
| `controller` | Room controller; optionally opens the browser operator |
|
||
| `cabinet` | Managed game and, when enabled, its local Pi GPIO bridge |
|
||
| `all` | Controller plus cabinet; useful for Windows simulation or a Pi hosting everything |
|
||
|
||
For the usual installation, run **controller on the PC/Mac** and **cabinet on each Pi**. Keep the launcher terminal open. These scripts do not install boot services or software packages.
|
||
|
||
## Files to deploy
|
||
|
||
Keep the following directory structure, either by copying the repository or creating this deployment folder:
|
||
|
||
```text
|
||
ArcadeEscape/
|
||
Start-Arcade.ps1
|
||
start-arcade.sh
|
||
ArcadeEscape.exe # Windows, with any accompanying export files
|
||
ArcadeEscape.arm64 # Pi, with any accompanying export files
|
||
tools/
|
||
launch/ # launch.py, examples, your launcher.ini
|
||
room_controller/ # server.py, operator.html, catalog.json
|
||
pi_gpio/ # pi_gpio_bridge.py
|
||
```
|
||
|
||
Use the executable appropriate to that machine. You can instead point the INI at an executable elsewhere. **All relative INI paths resolve from the INI's folder**, regardless of where you launch the script. Review your existing export location: the project's presets may place builds one directory above the repository.
|
||
|
||
## Windows controller
|
||
|
||
Install Python 3 first. From the project/deployment root:
|
||
|
||
```powershell
|
||
Copy-Item tools/launch/controller.example.ini tools/launch/launcher.ini
|
||
notepad tools/launch/launcher.ini
|
||
```
|
||
|
||
Fill in `operator_token` and `cabinet_tokens` with the same credentials already used by your cabinets. INI values here are **not surrounded by quotes**, except the JSON strings inside `cabinet_tokens`:
|
||
|
||
```ini
|
||
operator_token = YOUR_EXISTING_OPERATOR_TOKEN
|
||
cabinet_tokens = {"cabinet_01":"YOUR_EXISTING_CABINET_TOKEN"}
|
||
```
|
||
|
||
Each token must be distinct and at least 16 characters. Existing `ARCADE_OPERATOR_TOKEN`, `ARCADE_CABINET_TOKENS`, and legacy `ARCADE_CABINET_TOKEN` environment variables take precedence. Reuse credentials; the launcher does not generate or rotate them.
|
||
|
||
The launcher prints the configuration path and token source without printing the tokens. It warns when an environment operator/cabinet token overrides a different INI value, and rejects surrounding token quotes.
|
||
|
||
### Browser says Unauthorized
|
||
|
||
The controller was reached, but its operator token does not match what was entered. Use the **operator** token, not a cabinet token, and open the exact operator URL printed by the launcher. “Waiting for the room operator” in the game is normal until a scenario is prepared.
|
||
|
||
If you configured `operator_token` in `launcher.ini` but the launcher reports an environment override, stop your running stack with Ctrl+C and clear the old variable **in the same PowerShell terminal you use to launch**:
|
||
|
||
```powershell
|
||
Remove-Item Env:ARCADE_OPERATOR_TOKEN -ErrorAction SilentlyContinue
|
||
.\Start-Arcade.ps1 -Mode all -Browser
|
||
```
|
||
|
||
Use `-Mode controller` instead if this machine only hosts the controller. Enter the INI's operator token in the browser, without quotes. Clearing the variable affects only that PowerShell session; it does not delete an INI value or change a stored Windows environment variable. The controller must be restarted to pick up credential changes. Never paste real tokens into troubleshooting messages.
|
||
|
||
**Set `database` to your existing controller database** when upgrading. The example defaults to a new `tools/launch/state/arcade_room.sqlite3`; that would start a fresh controller history instead of using a database at the project root. To use a root-level database from the default INI location, set `database = ../../arcade_room.sqlite3`.
|
||
|
||
Then validate and start:
|
||
|
||
```powershell
|
||
.\Start-Arcade.ps1 -Mode controller -Check
|
||
.\Start-Arcade.ps1 -Mode controller -Browser
|
||
```
|
||
|
||
If PowerShell blocks script execution, the same launcher can be run directly without changing execution policy:
|
||
|
||
```powershell
|
||
py -3 tools/launch/launch.py controller --check
|
||
py -3 tools/launch/launch.py controller --browser
|
||
```
|
||
|
||
## Pi cabinet
|
||
|
||
Install the GPIO dependencies once, following the [GPIO guide](../pi_gpio/README.md). Configure the game's physical controls using the normal launcher before starting managed mode.
|
||
|
||
```sh
|
||
sudo apt update
|
||
sudo apt install python3-gpiozero python3-lgpio
|
||
cp tools/launch/pi.example.ini tools/launch/launcher.ini
|
||
nano tools/launch/launcher.ini
|
||
chmod +x ArcadeEscape.arm64
|
||
```
|
||
|
||
Set the game executable path, cabinet ID, bridge controller ID, and BCM pin allowlist. GPIO is enabled in this Pi example. Leave `url` and `token` blank to reuse the game's existing `user://arcade_network.cfg`, or supply them here:
|
||
|
||
```ini
|
||
[cabinet]
|
||
executable = ../../ArcadeEscape.arm64
|
||
id = cabinet_01
|
||
url = http://CONTROLLER_IP:8766
|
||
token = YOUR_EXISTING_CABINET_TOKEN
|
||
gpio = true
|
||
```
|
||
|
||
Do not copy operator credentials to a cabinet-only Pi. URL/token environment variables still override these INI values. Unlike the launcher INI, Godot's own CFG file requires double quotes around string values.
|
||
|
||
```sh
|
||
bash start-arcade.sh cabinet --check
|
||
bash start-arcade.sh cabinet
|
||
```
|
||
|
||
This starts the GPIO bridge first, waits for its local heartbeat endpoint, then launches the managed game with real GPIO enabled. The bridge uses **8765 locally**; the room URL uses **8766 on the controller**. `--check` validates files, settings, dependencies, and service port availability; it does not drive GPIO or prove wiring/permissions/network credentials work.
|
||
|
||
For Pi gameplay/network testing without physical outputs, set `gpio = false`. For a Pi that also hosts the controller, add the `[controller]` settings from the controller example and use `all` mode; blank cabinet URL/token then use that local controller's values.
|
||
|
||
## Windows all-in-one test
|
||
|
||
Copy `windows-all.example.ini` to `launcher.ini`, fill in the controller tokens, and set the Windows executable path. Keep `gpio = false`:
|
||
|
||
```powershell
|
||
.\Start-Arcade.ps1 -Mode all -Check
|
||
.\Start-Arcade.ps1 -Mode all -Browser
|
||
```
|
||
|
||
The game connects to the local controller using its cabinet ID's token. GPIO runs in simulation; Windows does not start the physical Pi bridge. To connect a Windows game to a remote controller instead, configure the cabinet section and use `-Mode cabinet`.
|
||
|
||
## Stopping, logs, and configuration
|
||
|
||
- **Ctrl+C** stops the stack started by this invocation. On the Pi, the bridge receives SIGTERM so its normal output cleanup runs.
|
||
- **Escape/game exit** also stops services started by that same invocation. A controller launched separately on another machine stays running.
|
||
- An unexpected child exit stops the other owned processes and returns an error; the launcher does not automatically restart a game or repeat hardware actions.
|
||
- An occupied service port causes startup to stop. Existing processes are never killed or silently adopted.
|
||
- Logs append to `tools/launch/logs/controller.log`, `gpio.log`, and `cabinet.log` by default. Check them for application errors after startup.
|
||
- Keep the database and GPIO request ledger across restarts. Do not delete them to replay a reward.
|
||
- Use `-Config C:\path\launcher.ini` on Windows or `--config /path/launcher.ini` on the Pi for another configuration file.
|
||
- `launcher.ini`, `*.local.ini`, the default logs, and the default state folder are Git-ignored within `tools/launch/`. Keep other private configuration paths out of Git yourself.
|
||
- Controller firewall rules, Godot exports, catalog generation, and GPIO wiring are still one-time deployment tasks; see the [room controller guide](../room_controller/README.md).
|
||
|
||
For macOS controller use: `bash start-arcade.sh controller --browser`, with Python 3 and a configured controller INI.
|