MuPiBox Documentation MuPiBox NG

GPIO and pin reference

Which GPIO pins (BCM) the MuPiHAT, power button, fan, LEDs, buttons and rotary encoder use, which are free and how they affect each other.

Many MuPiBox features depend on the Raspberry Pi's 40-pin GPIO header. This page lists which pins are used and what to watch out for when you connect your own buttons.

BCM number or pin number?

The admin interface always expects BCM numbers (the chip's GPIO number, e.g. "GPIO 17"), not the physical pin number on the header. GPIO 17, for example, is on physical pin 11. The table below gives both.

Used pins

BCMPinUsed byNote
2 (SDA)3I²C – MuPiHAT charger chipbus 1, address 0x6B, 50 kHz
3 (SCL)5I²C – MuPiHAT charger chipdo not use for buttons when the MuPiHAT is active
47MuPiHAT power cut (gpio-poweroff)cuts the power after shutdown
1711MuPiHAT power button (gpio-shutdown)kernel key KEY_POWER, see standby
1232Fan (default)hardware PWM possible (PWM0)
1333Power LED (MuPiHAT+ J15, default)hardware PWM possible (PWM1)
1636MuPiHAT amplifier MAX98357A SD_MODEonly with MuPiHAT audio
1812I²S BCLK (MuPiHAT audio)only with MuPiHAT audio
1935I²S LRCLK (MuPiHAT audio)only with MuPiHAT audio
2140I²S DATA (MuPiHAT audio)only with MuPiHAT audio

Without a MuPiHAT only the pins you enter yourself for fan, LED, buttons or rotary encoder are used.

Good free pins

For buttons and a rotary encoder with a MuPiHAT, BCM 5, 6, 22, 23, 24, 25, 26 and 27 work well (physical pins 29, 31, 15, 16, 18, 22, 37, 13). Avoid BCM 7–11 if you use SPI devices and BCM 14/15 if the serial console is active.

Displays, RFID and Bluetooth

  • DSI displays (official touch display, Waveshare DSI) use no GPIO pins; picture and touch run over the DSI ribbon cable.
  • HDMI displays with USB touch use no GPIOs either. Displays plugged onto the GPIO header (SPI displays) are not supported.
  • RFID readers connect via USB (USB HID or PN532 via USB-UART), see RFID.
  • Bluetooth and Wi-Fi are built in or connected via USB.

config.txt and overlays

Hardware such as the MuPiHAT, the power button or the display is enabled at boot through entries in /boot/firmware/config.txt (older systems: /boot/config.txt). MuPiBox only writes inside its own marked block and never changes lines outside it. The MuPiHAT installer, for example, puts its lines below #--------MuPiHAT--------; they stay untouched.

The MuPiHAT base configuration is:

dtparam=i2c_arm=on
dtparam=i2c1=on
dtparam=i2c_arm_baudrate=50000
dtparam=gpio=on
dtoverlay=gpio-poweroff,gpiopin=4,active_low=1
dtoverlay=gpio-shutdown,gpio_pin=17,active_low=1,gpio_pull=up

MuPiHAT audio adds dtoverlay=max98357a,sdmode-pin=16 and dtoverlay=i2s-mmap. The admin interface detects contradicting entries and reports them as a conflict instead of overwriting them (MuPiHAT).

Power button without a MuPiHAT

Standby needs a button that the kernel reports as KEY_POWER. Without a MuPiHAT you set it up yourself in config.txt, for example on BCM 3:

dtoverlay=gpio-shutdown,gpio_pin=3,active_low=1,gpio_pull=up

BCM 3 has one advantage: a press also wakes the Pi from the halted state (as long as it has power). But BCM 3 is also the I²C clock line. With a MuPiHAT never use BCM 3 for the button – the MuPiHAT brings its own button on BCM 17 anyway.

The Display & power page shows under "Power button diagnostics" which button the running kernel has actually loaded.

Interactions at a glance

If …then …
the MuPiHAT is activeBCM 2, 3, 4, 17 (and with audio 16, 18, 19, 21) are taken.
standby is enabledMuPiBox reads the power button itself; the kernel no longer shuts down on a press.
a power cut (gpio-poweroff) is loadedthe hardware switches off on a long press; MuPiBox's 3-second function is not offered.
fan and LED should use hardware PWMdtoverlay=pwm-2chan,pin=12,func=4,pin2=13,func2=4 is needed; otherwise MuPiBox switches them in software.
buttons sit on MuPiHAT pinsneither the buttons nor the MuPiHAT work reliably.