room_glitch/docs/remote_pi_start.md

Start the Pi cabinets from the controller PC

After one-time setup, your usual command starts the Windows controller, opens the browser, and asks each configured Pi to start its cabinet service:

.\Start-Arcade.ps1 -Mode controller -Browser

The Pi service runs the existing cabinet launcher, which starts its GPIO bridge when enabled and then the managed game. SSH disconnects after the start request; the service stays running on the Pi. Already-running services are not restarted. Starting the apps does not automatically prepare or start a scenario; continue doing that in the operator.

The Pis must be powered on, reachable, and logged into their graphical desktop. This is remote application startup, not remote power-on. Desktop autologin is useful for cabinets; configure it on each Pi if desired.

1. Install the cabinet service on each Pi

Copy the updated tools/launch/ scripts to the Pi's deployment folder. Stop the manually running cabinet launcher with Ctrl+C first so it releases the GPIO bridge port.

From a terminal on the Pi desktop, as the normal account that runs the game (without sudo):

python3 tools/launch/pi_service.py install --config tools/launch/launcher.ini

Use your actual INI filename, such as launcher-pi.ini, if different. It must contain that Pi's executable path, cabinet ID, controller URL/token (or blank URL/token to use its existing Godot CFG), and GPIO settings. The installer records the absolute config path; rerun it if the deployment/config moves.

This creates:

• ~/.config/systemd/user/arcade-cabinet.service: runs your existing managed launcher as the desktop user.
• ~/.config/autostart/arcade-cabinet-display.desktop: refreshes display settings at each desktop login, without launching the game.
• A temporary display environment file under the user's runtime directory, refreshed immediately during installation.

The installer does not start the game, enable boot startup, configure SSH, or change OS autologin. It captures only display-related variables, not application tokens. The service clears inherited ARCADE_* credential/URL overrides, so keep its intended settings in the configured INI or Godot CFG rather than relying on a terminal's environment.

Test locally:

systemctl --user start arcade-cabinet.service
systemctl --user status arcade-cabinet.service

Confirm the game appears on the cabinet monitor and becomes ONLINE. To stop it:

systemctl --user stop arcade-cabinet.service

If display settings change, run python3 tools/launch/pi_service.py refresh-session from the current Pi desktop terminal before starting it again.

2. Set up SSH access from Windows

SSH must be enabled on each Pi. Use the same SSH username as the desktop account where you installed the service.

These are SSH keys, separate from the 16-character application tokens in the cabinet setup guide. The tokens cannot authenticate SSH.

Generate a dedicated key on the PC (do not overwrite an existing one):

ssh-keygen -t ed25519 -f "$env:USERPROFILE\.ssh\arcade_cabinets" -C "arcade-controller"

If you use a passphrase, load the key into your SSH agent before launching the room. Automated startup uses batch mode and cannot ask for passwords or passphrases.

For each Pi, first connect interactively and verify its host fingerprint before trusting it:

ssh PI_USER@PI_HOST

Log out with exit. To authorize the public key on that Pi, run from PowerShell (substitute its real user and host):

Get-Content "$env:USERPROFILE\.ssh\arcade_cabinets.pub" | ssh PI_USER@PI_HOST 'umask 077; mkdir -p ~/.ssh; cat >> ~/.ssh/authorized_keys'

Only copy the .pub key; the private key stays on the PC. Test unattended access:

ssh -i "$env:USERPROFILE\.ssh\arcade_cabinets" -o BatchMode=yes -o StrictHostKeyChecking=yes PI_USER@PI_HOST "systemctl --user status arcade-cabinet.service"

An inactive service may return a nonzero status; confirm SSH succeeded and systemd found the installed unit. The launcher keeps host-key checking enabled and never automatically accepts a new or changed host key.

3. Add the Pi list to the PC launcher INI

Merge this into the controller INI you actually launch with. Replace each host and username:

[remote]
enabled = true
cabinets = [{"id":"cabinet_01","host":"PI_1_HOST","user":"PI_USER","identity_file":"~/.ssh/arcade_cabinets"},{"id":"cabinet_02","host":"PI_2_HOST","user":"PI_USER","identity_file":"~/.ssh/arcade_cabinets"},{"id":"cabinet_03","host":"PI_3_HOST","user":"PI_USER","identity_file":"~/.ssh/arcade_cabinets"}]

identity_file is optional if your default SSH identity or agent is already configured. port is optional and defaults to 22. Each ID must exist in the controller catalog and its cabinet-token map. The Pi's own launcher must use the same cabinet ID; this list does not remotely rewrite its identity or credentials.

Validate, then launch:

.\Start-Arcade.ps1 -Mode controller -Check
.\Start-Arcade.ps1 -Mode controller -Browser

Use -Config tools/launch/launcher-pc.ini if that is your actual config filename. -Check validates local settings only; it does not contact or start a Pi.

The controller starts first. The launcher sends the SSH requests concurrently, then checks controller heartbeats. It prints separate SSH OK/FAILED and ONLINE/OFFLINE results, so a successful service command is not mistaken for a working game connection. A failed/offline Pi leaves the controller running for troubleshooting.

Operating behavior

• Starting the controller again leaves active Pi services running; it does not interrupt their games with restart.
• Closing the browser or stopping the PC controller leaves the Pi services running. They reconnect when the controller returns.
• Closing the Pi game with Escape stops that Pi's launcher/bridge. It will not restart automatically; the next controller launch can start it again.
• A crash is not automatically restarted, avoiding unexpected game resets during a room session.
• Use ssh PI_USER@PI_HOST "systemctl --user stop arcade-cabinet.service" for an intentional remote stop.
• Application logs remain in the Pi launcher's configured log folder. Service startup errors are available through journalctl --user -u arcade-cabinet.service -n 60 --no-pager.
• If the PC launches before the Pi desktop is ready, startup can fail. Wait for desktop login and launch the controller again, or issue the same systemctl --user start command over SSH. There is no automatic power-on or infinite retry loop.
• After a desktop restart/logout, confirm the display helper has run before starting games. If your desktop does not honor XDG autostart entries, run pi_service.py refresh-session locally and check the desktop's startup configuration.

The service can be removed by stopping it, removing the two managed files listed above, and running systemctl --user daemon-reload. Game resources, saved control mappings, tokens, and GPIO ledger are unaffected.

Implementation references: OpenSSH client configuration, systemd execution environment, and systemd desktop integration.