The pigpio C and Python library strictly enforces Broadcom SOC channel (BCM) numbering. If you pass a physical board pin number into gpioSetMode() or gpioWrite(), your code will compile, but it will toggle the wrong silicon pad, potentially shorting a bus or bricking your peripheral. Below is the definitive reference for mapping physical headers to pigpio's expected BCM logic.

The Complete pigpio BCM Reference Table

This table isolates the pins most critical for embedded control. pigpio ignores physical layout; it only cares about the BCM column. Always wire your hardware based on the Physical column, but write your code using the BCM column.

BCM Pin Physical Pin Name pigpio Function & Practical Notes
2 3 SDA1 I2C Data. Note: Has a physical 1.8kΩ pull-up to 3.3V on the Pi board. Do not use as a standard GPIO output.
3 5 SCL1 I2C Clock. Note: Also has a 1.8kΩ physical pull-up to 3.3V.
4 7 GPCLK0 General Purpose Clock. Often used for software PWM via gpioPWM(), but not hardware PWM.
14 8 TXD UART Transmit. Defaults to serial console; must disable in raspi-config before using with pigpio.
15 10 RXD UART Receive. Same serial console caveat as BCM 14.
17 11 GPIO17 Standard GPIO. Commonly used for SPI CE1 or basic digital I/O.
18 12 PCM_CLK Hardware PWM0. The most reliable pin for gpioHardwarePWM() to drive servos or dim LEDs.
27 13 GPIO27 Standard GPIO. Often paired with BCM 22 for H-bridge motor control.
22 15 GPIO22 Standard GPIO. Safe for general input/output.
23 16 GPIO23 Standard GPIO. Commonly used for SPI MISO or relay triggering.
24 18 GPIO24 Standard GPIO. Commonly used for SPI CE0.
10 19 MOSI SPI Master Out Slave In. Use spiOpen() in pigpio to manage this bus.
9 21 MISO SPI Master In Slave Out.
25 22 GPIO25 Standard GPIO. Safe for general input/output.
11 23 SCLK SPI Clock.
8 24 CE0 SPI Chip Select 0.
7 26 CE1 SPI Chip Select 1.
12 32 PWM0 Hardware PWM0 (Alt). Secondary pin for hardware PWM channel 0.
13 33 PWM1 Hardware PWM1. Independent hardware PWM channel.
19 35 PCM_FS Hardware PWM1 (Alt). Secondary pin for hardware PWM channel 1.

Numbering Standards: BCM vs. Physical vs. WiringPi

In the embedded Linux ecosystem, 'regional standards' translate to competing pin numbering schemes. Understanding which standard applies to your codebase prevents catastrophic wiring errors.

1. BCM (Broadcom SOC Channel)

Which standard applies: This is the only standard supported by the pigpio library. It maps directly to the Broadcom silicon die pad numbers. If you are writing C/C++ or Python using pigpio, you must use BCM numbers in every function call.

2. Physical (Board Numbering)

Which standard applies: Used exclusively for physical wiring, counting from 1 to 40 down the header. Never pass a physical pin number into pigpio. For example, Physical Pin 11 is BCM 17. If you call gpioSetMode(11, PI_OUTPUT) in pigpio, you are actually toggling BCM 11 (Physical Pin 23, SPI SCLK), which will corrupt your SPI bus if a device is attached.

3. WiringPi (Legacy)

Which standard applies: A deprecated numbering scheme created by Gordon Henderson to mimic Arduino pinouts (e.g., WiringPi pin 0 = BCM 17). WiringPi is unmaintained and does not support newer Pi boards. If you are porting legacy code to pigpio, you must completely rewrite the pin definitions using the Pinout.xyz BCM map.

⚠️ Pi 5 RP1 Chip Warning: The Raspberry Pi 5 replaced the Broadcom GPIO controller with the custom RP1 chip. While the physical 40-pin header remains identical, the underlying memory addresses changed. The classic pigpio daemon requires specific patches or the newer lgpio library to function correctly on Pi 5. For Pi 5 projects in 2026, verify your pigpio version supports the RP1 silicon, or switch to the official rpi-gpio Python module.

The Rows People Get Wrong: Common pigpio Traps

Even experienced makers trip over specific hardware quirks when transitioning from basic GPIO toggles to advanced bus protocols. Here are the most frequent bench failures.

  • The Hardware PWM Illusion (BCM 4 vs BCM 18): Many tutorials suggest using BCM 4 for PWM because it works with pigpio's gpioPWM() function. However, gpioPWM() generates software PWM using DMA timers, which causes servo jitter under CPU load. For true, jitter-free hardware PWM, you must use gpioHardwarePWM(), which only routes to BCM 12, 13, 18, and 19.
  • The I2C Pull-Up Trap (BCM 2 & 3): Developers often configure BCM 2 and 3 as standard inputs to read a button, forgetting that the Raspberry Pi board includes physical 1.8kΩ pull-up resistors to the 3.3V rail on these specific pins. If you wire a 5V sensor directly to these pins without a level shifter, the 1.8kΩ pull-up will backfeed 5V into the Pi's 3.3V regulator, potentially destroying the SoC.
  • UART Console Collision (BCM 14 & 15): By default, the Pi outputs kernel boot logs to the UART TX pin (BCM 14). If you connect an ESP32 or Arduino to these pins and boot the Pi, the barrage of 115200 baud serial garbage will confuse your microcontroller. You must disable the serial console via sudo raspi-config (Interface Options -> Serial Port -> Login shell: No, Hardware: Yes) before using pigpio's serialOpen().
  • SPI CE Pin Confusion (BCM 7 & 8): pigpio's spiOpen() function automatically manages the Chip Enable lines. If you manually try to toggle BCM 8 (CE0) using gpioWrite() while the SPI bus is open, you will cause race conditions. Let the pigpio SPI driver handle the CE pins.

Safe Interpretation When Board Markings Fade

On older Raspberry Pi 3B+ or Zero W boards, the silkscreen pin markings often wear off, and third-party clone boards frequently omit them entirely. Guessing pin 1 by eye leads to reversed polarity, instantly killing the 3.3V LDO regulator.

The Multimeter Ground-Plane Method:
Do not rely on visual counting. Grab your multimeter, set it to continuity mode (the diode/beep setting), and use the metal shielding of the USB or Ethernet ports as your known ground reference. Probe the header pins until you find the ground cluster. According to the official Raspberry Pi hardware documentation, Physical Pins 6, 9, 14, 20, 25, 30, 34, and 39 are all tied to ground. Once you locate a confirmed GND pin, you can reliably orient the board.

Bench Rule of Thumb: Pin 1 is always the square solder pad. If the silkscreen is gone, look closely at the pads under a magnifying glass. Pin 1 is square; all other pins are perfectly round. Furthermore, Pin 1 is always located on the side of the header closest to the SD card slot, not the side closest to the USB ports.

Frequently Asked Questions

Why does pigpio throw an error or toggle the wrong pin when I use physical pin 11?

pigpio does not have a 'physical pin mode' like the RPi.GPIO Python library does. When you call gpioInitialise(), it locks into BCM mode exclusively. If you pass 11 into gpioSetMode(11, PI_OUTPUT), pigpio assumes you mean BCM 11 (Physical Pin 23, SPI Clock). To toggle Physical Pin 11, you must look up its BCM equivalent (BCM 17) and use gpioSetMode(17, PI_OUTPUT).

Which BCM pins support true hardware PWM in pigpio?

True hardware PWM, driven by the SoC's dedicated PWM peripheral rather than DMA-hacked software timers, is only available on BCM 12, 13, 18, and 19. These map to two independent channels: Channel 0 (BCM 12 and 18) and Channel 1 (BCM 13 and 19). If you need to drive two servos without jitter, use BCM 18 and BCM 13 to ensure they are on separate hardware channels.

How do I safely probe a pigpio pin without shorting the 3V3 rail?

The 3.3V power pins (Physical 1 and 17) sit directly adjacent to GPIO pins (Physical 3 and 11). Slipping with a standard multimeter probe can bridge 3.3V into a GPIO configured as an output-low, creating a dead short that will fry the SoC's internal bonding wires. Always use a GPIO breakout board with labeled screw terminals or a logic analyzer with dedicated flying-lead clips. If you must probe the bare header, use fine-point 0.5mm needle probes and brace your hand against the board edge to prevent slipping.