Debug GPIO from the shell with pinctrl: see pin modes, set levels, watch signals

When a sensor doesn't respond, first check what the pin actually is: input or output, which alternate function (I2C, UART, SPI…), and whether it's high or low. pinctrl from raspberrypi/utils does this. It's the more powerful replacement for raspi-gpio, and it reads the hardware directly, bypassing kernel drivers, so it shows the real state.

sudo pinctrl                   # state of all GPIOs: function, pull, level
sudo pinctrl -p                # same, but by 40-pin header pin number
sudo pinctrl -l                # list detected GPIO controllers
pinctrl funcs 9-11             # which alternate functions GPIO 9–11 support
sudo pinctrl 4,6 op dl         # make GPIO 4 and 6 outputs, driving low
sudo pinctrl poll BT_CTS,BT_RTS   # watch level changes continuously
pinctrl help                   # full usage

Pins can be referred to by number or by name, and the get/set keywords are optional in most commands.

Typical uses

• "Is I2C actually enabled on GPIO 2/3?" Check that they show the I2C alternate function, not input/output.
• Check a button or sensor output without writing code: pinctrl poll <gpio> shows level changes live. For slow signals (up to a few hundred kHz) it works as a basic logic analyser.
• Find a conflict: if your overlay should have claimed a pin but pinctrl shows another function, another overlay or HAT EEPROM configuration got there first.

Cautions

• Because it bypasses the kernel, setting a pin with pinctrl while a driver or your application also controls it gives confusing results. Use it for inspection and quick tests, not as your application's GPIO layer (use gpiozero/lgpio for that).
• It needs root by default. Raspberry Pi OS ships a udev rule for /dev/gpiomem*, so membership of the gpio group is sufficient there.
• Never drive a pin as output into something that also drives it (e.g. a HAT's output).