A Raspberry Pi-style GPIO header does not make Pi HATs and GPIO libraries work

Symptom

A HAT or sensor project that works on a Raspberry Pi does nothing, or the Python script fails with import or device errors, after moving to a "Pi-compatible" alternative board.

Why

"Compatible header" usually means the physical pin layout (power, ground, and some I2C/SPI/UART positions) matches. It does not mean:

• Same header size. The Orange Pi 5 has a 26-pin header, so 40-pin HATs don't fit at all.
• Same software. Raspberry Pi GPIO libraries and many HAT drivers are written for Broadcom SoCs and Raspberry Pi OS device-tree overlays. Other SoCs (Rockchip, Allwinner, Amlogic) have different GPIO controllers, pin numbering and overlays.
• Same camera/display connectors. CSI/DSI connectors and their drivers are board- and SoC-specific.
• Same pin functions. Even with an identical layout, which pins can do PWM, a second UART or SPI chip-select differs.

What to do

1. Read the board's own pin definition (vendor wiki/product page), not a Raspberry Pi pinout.
2. Use the vendor's GPIO tooling, e.g. Orange Pi's wiringOP (a wiringPi port; gpio readall prints the pin map), or the generic Linux interfaces (the GPIO character device via libgpiod, /dev/i2c-*, /dev/spidev*) which work across SoCs once the right overlay is enabled.
3. Enable interfaces through the vendor's mechanism (device-tree overlays in the vendor or Armbian configuration), not raspi-config.
4. Check HAT drivers before buying: if a HAT needs a Raspberry Pi OS kernel module or overlay, assume it won't work unless the board vendor documents support.
5. Prefer USB or I2C/SPI sensors with plain Linux drivers for designs that must move between boards.