84 lines
5.9 KiB
Markdown
84 lines
5.9 KiB
Markdown
# Real GPIO on the Raspberry Pi
|
||
|
||
After completing the hardware setup below, the [stack launch scripts](../launch/README.md) can start the bridge and managed cabinet together.
|
||
|
||
The former HardwareManager only logged `[MOCK GPIO]`; it could not light an LED. The standalone launcher also did not forward game events to hardware. Both paths are now connected. GPIO numbers in HardwareAction resources are **BCM numbers**, not physical header positions.
|
||
|
||
## 1. Wire the LED (Pi powered off)
|
||
|
||
For a typical small red LED:
|
||
|
||
```text
|
||
physical pin 11 (BCM GPIO17) -> 330–470 ohm resistor -> LED anode (long leg)
|
||
LED cathode (short leg / flat side) -> physical pin 6 (GND)
|
||
```
|
||
|
||
Keep the LED's legs in different breadboard rows. The resistor must be in series, not bypassed by another wire. Physical pin **17 is 3.3V power**, not GPIO17. Do not use the 5V rail for this test. GPIO is 3.3V logic; coin dispensers, relay coils and other powered loads require an appropriate driver, not a direct GPIO connection.
|
||
|
||
Pinout and LED reference: [GPIO Zero recipes](https://gpiozero.readthedocs.io/en/stable/recipes.html#pin-numbering).
|
||
|
||
## 2. Install dependencies on the Pi
|
||
|
||
Use a current Raspberry Pi OS installation and its packaged GPIO Zero/lgpio support (Pi 4 or Pi 5):
|
||
|
||
```sh
|
||
sudo apt update
|
||
sudo apt install python3-gpiozero python3-lgpio
|
||
```
|
||
|
||
The account running the helper needs access to `/dev/gpiochip*`. Raspberry Pi OS normally provides this via the `gpio` group. If you get a permission error, inspect `ls -l /dev/gpiochip*` and `groups`; if needed, run `sudo usermod -aG gpio "$USER"`, then log out and back in. The game itself does not need to run as root.
|
||
|
||
## 3. Test the wiring independently
|
||
|
||
Before running the bridge, run this on the Pi. The LED should remain lit for two seconds, then turn off:
|
||
|
||
```sh
|
||
GPIOZERO_PIN_FACTORY=lgpio python3 -c 'from gpiozero import LED; from time import sleep; led=LED(17); led.on(); sleep(2); led.off(); led.close()'
|
||
```
|
||
|
||
If this fails, fix the reported GPIO permissions/package error or check the resistor, LED orientation, breadboard connections and pin numbering before testing the game. A successful command without light does not prove the wiring is correct.
|
||
|
||
## 4. Start the GPIO helper
|
||
|
||
Copy **pi_gpio_bridge.py** from this folder alongside the exported game on the Pi. It is a separate Python program, not an embedded Godot resource. Keep it running in a terminal:
|
||
|
||
```sh
|
||
GPIOZERO_PIN_FACTORY=lgpio python3 pi_gpio_bridge.py --controller cabinet_01_gpio --pins 17
|
||
```
|
||
|
||
It listens only on `127.0.0.1:8765` and owns the allowed pins. Do not run another LED script at the same time. It accepts only the configured controller ID and listed BCM pins. Add `,20` to the pin list later if you wire the configured Start Light as well. Do not enable other pins without checking their wiring.
|
||
|
||
## 5. Run the exported game with real outputs
|
||
|
||
In another terminal, replacing `ArcadeEscape.arm64` with your actual executable filename:
|
||
|
||
```sh
|
||
./ArcadeEscape.arm64 -- --gpio=real --gpio-test
|
||
```
|
||
|
||
`--gpio-test` sends a two-second pulse on cabinet 01's coin-release output (BCM17) at startup. No game win is required. The launcher shows GPIO status and the helper terminal logs each accepted command. Once that works, omit the test flag:
|
||
|
||
```sh
|
||
./ArcadeEscape.arm64 -- --gpio=real
|
||
```
|
||
|
||
Choose Pac-Man and win its configured objective. The launcher's **Hardware Scenario** defaults to `proof_of_concept.tres`: `game_won` -> cabinet 01 `coin_release` -> BCM17, active-high, **600 milliseconds**. This is only a short flash. Other launcher games only send hardware events if they have a matching assignment in the selected Hardware Scenario. Add their event mappings in your resources as needed.
|
||
|
||
Without `--gpio=real`, runtime outputs remain simulated, including on Windows. Real mode does not silently fall back to simulation if the helper fails. Connection failures, wrong-controller requests and rejected pins appear in the launcher status/log. The editor's room simulation should be run without real mode. This bridge controls the Pi running the game, not GPIO on a different Pi across the network.
|
||
|
||
## Timing and stopping
|
||
|
||
Managed room rewards include a unique `request_id`. The updated helper records these in `~/.local/state/arcade_gpio/requests.sqlite3` (override with `--ledger`). Repeated IDs return the earlier result without driving the pin again. An interrupted request with no recorded outcome is marked uncertain and will not be replayed. Keep this ledger across restarts; standalone requests without an ID retain the original retrigger behavior.
|
||
|
||
The helper controls pulse timing; repeated pulses restart that pin's duration. Digital outputs accept `context.active=false` to switch off. Active-low polarity is supported by GPIO Zero. Conflicting polarity on the same pin is rejected until the helper restarts.
|
||
|
||
The game sends a heartbeat every second. If it exits or disconnects, outputs become inactive within roughly three seconds; short pulses still finish at their own deadline. Ctrl+C/SIGTERM shuts down the helper and deactivates its outputs. This is a software watchdog, not a hardware safety circuit; power loss or forcibly killing the helper cannot guarantee pin state. Test with the LED before attaching real actuators.
|
||
|
||
Keep the helper running while restarting games with Escape. For unattended boot, launch the helper under your Pi's service manager using the same account/environment and start the game with `--gpio=real`.
|
||
|
||
## Validation performed off-Pi
|
||
|
||
Bridge tests cover pulse timing/retriggering, active-low configuration, digital off, watchdog expiry, rejected pins/controllers, and shutdown. The Godot integration test sends a real HTTP request from a Pac-Man win to a test bridge with fake GPIO devices. Physical voltage and your wiring must still be verified on the Pi.
|
||
|
||
References: [GPIO Zero installation](https://gpiozero.readthedocs.io/en/stable/installing.html), [output device API](https://gpiozero.readthedocs.io/en/stable/api_output.html).
|