# GPIO: connecting code to buttons and lights

[Concepts explained](README.md)

**GPIO** means *General Purpose Input/Output*. A pin configured as an input reads an electrical level; an output sets one. Raspberry Pi GPIO uses 3.3-volt logic. See [Raspberry Pi's GPIO explanation](https://pip-assets.raspberrypi.com/categories/685-whitepapers-app-notes/documents/RP-006553-WP/A-history-of-GPIO-usage-on-Raspberry-Pi-devices-and-current-best-practices).

The connector also has power and ground pins, which are not interchangeable with programmable GPIO. Check the [official GPIO reference](https://www.raspberrypi.com/documentation/computers/raspberry-pi.html#gpio-and-the-40-pin-header).

## Turn a signal into a decision

Pliro represents digital pin levels as Boolean values: `true` or `false`. A button's wiring determines whether pressed means high or low. Your program has to use the convention of the component it reads.

| Idea | Pliro operation | Example |
| --- | --- | --- |
| Configure an output | `pinOutput(pin)` | Prepare a pin for an LED signal. |
| Configure an input | `pinInput(pin)` | Prepare a pin for a button signal. |
| Set an output level | `writePin(pin, value)` | Set it high with `true`. |
| Read a logical level | `readPin(pin)` | Use an input in an `if` condition. |

Configure each pin before using it. Writing requires an output and a Boolean. Reading an output gives its last successfully written value; reading an input gets its current logical level. Pliro accepts whole BCM pin numbers from 0 through 27.

## Practice without wires

Run this in the IDE and watch virtual BCM 17 in the hardware workbench:

```pliro
# language: en
let ledPin = 17
pinOutput(ledPin)
writePin(ledPin, true)
wait(1)
writePin(ledPin, false)
say readPin(ledPin)
```

The output becomes high for one second, then low. The console prints `false`. Try making the wait two seconds.

Interpreter and browser sessions use virtual pins. An input starts as `false` unless a host, such as the IDE's virtual component, supplies a value. Running this code in the IDE does not operate a physical Pi.

An exported application built for an explicit [Raspberry Pi target](raspberry-pi.md) uses the Linux GPIO device when run on that Pi. Missing device access is reported as a runtime error.

## Match the name to the connection

**BCM numbering** identifies the GPIO signal, rather than its position on the header. On the standard 40-pin header, BCM 17 is physical pin 11. Follow your board's pinout. Use a resistor with an LED, never feed 5 V into a GPIO input, and use a suitable driver rather than connecting a motor directly. See the [manufacturer's wiring guidance](https://www.raspberrypi.com/documentation/computers/raspberry-pi.html#gpio-and-the-40-pin-header).

## A digital sensor is a yes-or-no input

In Pliro's workbench, a threshold sensor can report whether a value crosses a chosen boundary. `readPin` still returns a Boolean, not a temperature or a continuously varying voltage. Think “above the threshold?” rather than “how many degrees?”

[Pin-control guide](../guides/gpio.md) · [Raspberry Pi](raspberry-pi.md) · [Boolean values](../syntax/boolean.md)