01 Overview

GPIO is the most basic way for the ESP32 to exchange signals with the outside world. Each pin can be configured as input or output, with internal pull-up/pull-down, interrupt triggers (rising, falling, any edge), and open-drain mode.

This example demonstrates how to initialize GPIO, read button states, control relays, and handle interrupts. It solves the most common I/O needs in products: detecting external level changes and driving actuators.

Typical applications include: device panel buttons, door/magnetic alarm inputs, relay control (e.g., lights, pumps, fans), and simple level detection (e.g., comparator output for battery voltage).

GPIO is suitable for low-speed, non-timing-critical signals. For protocols requiring precise timing (e.g., WS2812, DHT11, or high-speed SPI), use dedicated peripherals like RMT, SPI, or I2S.

This example does not cover analog sampling (ADC), PWM output, or communication protocols; those are covered by other examples.

Understanding GPIO electrical characteristics and software configuration is fundamental to product stability; incorrect pull-ups or drive circuits can cause false triggers or device damage.

02 Hardware

• MCU: ESP32 family, 3.3V logic levels, most GPIO pins are 5V-tolerant (see datasheet), but avoid direct 5V signals.
• Power: 3.3V main supply; relays and other heavy loads need external power, never draw from GPIO.
• Button input: Button connects between GPIO and GND (or VCC), enable internal pull-up/pull-down to avoid floating.
• Relay output: Relay coil requires an external driver transistor (e.g., NPN or MOSFET) and a flyback diode (e.g., 1N4148) across the coil to absorb back EMF. GPIO cannot drive a relay directly.
• Level detection: Input signals must be divided down to 3.3V or below; consider Schmitt trigger or filter capacitor to suppress noise.
• ESD protection: For long cable inputs (e.g., door sensors), add TVS diodes and series resistors.
• Connectors: Choose pin headers, terminal blocks, or FPC based on product needs; mind pitch and current rating.
• Layout watch: Keep inductive loads like relays away from MCU and crystal to avoid EMI.

03 Software flow

1. Select GPIO pins per schematic, avoiding strapping pins (e.g., GPIO0, GPIO2, GPIO12) or confirm their boot state doesn't affect function.

2. Use gpio_config() to set direction, pull-ups/downs, and interrupt type. For buttons, enable internal pull-up (button to GND); for relays, set as push-pull output.

3. For buttons, use polling or interrupts. In the ISR, only set a flag; handle the actual logic in the main loop or a task.

4. Implement software debounce: after detecting a level change, wait 10-20ms and confirm, to avoid mechanical bounce.

5. For relays, add interlock logic: ensure conflicting relays (e.g., forward/reverse) are never on simultaneously.

6. In the main loop, act on button events, e.g., toggle relay state.

7. Error handling: if GPIO config fails, log and retry; if overcurrent is detected (via external circuit), turn off relays and alarm.

8. For low power: before sleep, set GPIOs to appropriate states (e.g., input pull-up or output low) and configure wake-up sources (e.g., EXT1).

04 Core points

• Strapping pins are not casual buttons. They have special functions at boot (e.g., GPIO0 affects download mode, GPIO12 affects voltage).
• Never drive a relay directly from GPIO. Use a driver transistor and flyback diode; otherwise you risk damaging the pin or causing system resets.
• Input signals must meet 3.3V logic levels. 5V signals need level shifting or division.
• Long cable inputs need ESD and filtering. Otherwise ESD or noise can cause false triggers or damage.
• Software debounce and interlock are mandatory for product quality. Ignoring them leads to false button presses or relay conflicts.
• Custom work: I/O map, protection circuitry, key/relay logic.