Know your pins.
Connect with confidence.

SAME SIGNALS. DIFFERENT BOARD SIZES.

Zero or full-size Pi?
The header matches.

Pin functions and enabled peripherals vary by model and configuration. A green pin here is a candidate, not proof it is free on your Pi. HATs, overlays and another application can claim any GPIO.

Two numbers. One actual pin.

Physical pin is the connector position, from 1 to 40. BCM / GPIO number identifies the signal used by ORBPuzzles and GPIO Zero.

Enter 17, not 11, in Admin > GPIO for this example. Power and ground positions do not have BCM input numbers.

The whole header.
At a glance.

View from the component / connector side, not the underside. This diagram is rotated to put physical pin 1 at the upper left; rotate your view to match your board’s pin-1 mark. A square solder pad often identifies pin 1 — confirm with your model’s documentation. Don’t rely on the HDMI or USB connector position.

• Input / output candidate
• GPIO / check shared function
• 3.3 V power / not an input
• 5 V power / not an input
• Ground / not an input
• HAT ID / leave unused

Start with these inputs.

For simple normally-open buttons or isolated dry-contact puzzle switches, these are good starting candidates. They can also be outputs — the role comes from your app configuration, not a separate input-only connector.

Other general candidates are BCM 5, 6, 16 and 26. Shared-function GPIO can also be inputs when their peripheral function is disabled and no driver claims them. Do not use one GPIO for both an input and output, or assign two separate events to the same pin.

Power isn’t a signal.

Amber means check first.

These are real GPIO signals, but beginner projects should leave them alone until the enabled peripherals and wiring are understood. Alternate functions do not permanently prevent GPIO use.

Other overlays, such as display interfaces, can claim additional pins — even the green candidates. If the app reports GPIO busy, don’t force the pin: remove the conflicting mapping and pick an unused one. See Pi troubleshooting.

Your first puzzle button.

Power down the Pi. Connect a normally-open button or isolated dry contact between BCM 17 / physical pin 11 and GND / physical pin 6. Do not add a connection to either power rail. ORBPuzzles uses GPIO Zero’s default button pull-up: pressing the button pulls the input low to ground.

Power up, open Admin > GPIO, and assign BCM 17 to Complete room. Test without a team in the room. Alternatively, before creating saved mappings, add:

GPIO_INPUTS={"complete-room":17}

To add a separate monitor-toggle button, use a different free pin, for example BCM 22 / physical pin 15, with its own button to GND:

GPIO_INPUTS={"complete-room":17,"display-toggle":22}

Use the second line instead of the first, not as a duplicate environment entry. Saved Admin > GPIO mappings take precedence. Restart after editing /etc/escape-room-screen/environment:

sudo systemctl restart escape-room-screen.service

Monitor toggle requires supported Pi monitor-control tooling. For reed switches and other puzzle sensors, use only verified dry contacts or a suitable 3.3 V interface — do not assume every sensor is voltage-free.

BEFORE THE FIRST PRESS

A careful final check.

• Match physical pin 1 to your board marking; don’t mirror the map from the underside.
• Use BCM numbers in the app and physical numbers to find the connector positions.
• Check your GPIO mappings, HATs and overlays before selecting an input.
• Power down before connecting wires; use a properly soldered header and secure connectors.
• Keep the 3.3 V and 5 V rails out of dry-contact button wiring.
• Use rated interface hardware and separate load power for outputs. This guide is not a mains, lock or safety-critical wiring design.

Pin assignments cross-checked against Pinout.xyz; button wiring and BCM numbering follow GPIO Zero documentation. Check your exact board’s Raspberry Pi documentation before wiring.