Raspberry Pi HAT GPIO Pin Conflicts: How to Check

To check whether two Raspberry Pi HATs share GPIO pins, you compare each HAT’s pin usage against the other, either by reading their EEPROM device tree overlays or by examining their documentation and schematics. This article explains the practical methods, the underlying mechanism, and how to resolve conflicts before they cause boot failures or erratic behavior.

What a HAT Actually Is

A HAT (Hardware Attached on Top) is a Raspberry Pi add-on board that follows a specific mechanical and electrical standard. The key feature that distinguishes a HAT from a generic GPIO expansion board is the onboard EEPROM. This small memory chip stores a device tree blob (DTB) fragment that describes which GPIO pins the HAT uses and how. When the Pi boots, it reads this EEPROM over the I2C bus (pins GPIO 0 and GPIO 1) and automatically loads the corresponding device tree overlay, configuring the pins for the HAT’s functions.

Because HATs are designed to stack, the standard defines a strict pinout for the 40-pin header. All HATs must use the same power and ground pins, and they must not use the pins reserved for the EEPROM (ID_SD and ID_SC). However, the remaining GPIO pins are shared across the header. Two HATs can both claim the same GPIO for different functions, leading to a conflict.

How the EEPROM and Device Tree Work

Each HAT’s EEPROM contains a binary blob that is read by the firmware at boot. The blob includes a magic number, a version, the board’s name, and a device tree overlay. The overlay is a small text-like structure that tells the Linux kernel which GPIOs to set as inputs, outputs, or alternate functions (like I2C, SPI, UART, PWM).

When you stack two HATs, the Pi reads both EEPROMs (if both have them) and attempts to apply both overlays. If the overlays request the same GPIO for different functions, the kernel will typically log an error and one of the overlays may fail to load. This can leave the corresponding HAT non-functional, or cause the Pi to boot into a degraded state.

To check for conflicts, you need to know what each overlay requests. The easiest way is to look at the HAT’s documentation, which usually lists the GPIO pins used. Alternatively, you can inspect the overlay source files on your Pi or on the official Raspberry Pi GitHub repository.

Method 1: Read the HAT EEPROM Overlay

If you already have the HATs connected, you can read the EEPROM contents using the i2c-tools package. The EEPROM is at I2C address 0x50 on the ID_SD/ID_SC pins. First, enable I2C and install the tools:

1. Run sudo raspi-config, go to Interface Options, and enable I2C.
2. Install i2c-tools with sudo apt install i2c-tools.
3. Run sudo i2cdetect -y 1 to see if a device appears at 0x50.
4. Dump the EEPROM with sudo i2cdump -y 1 0x50.

The raw dump is binary, but you can parse it with a tool like hats or by manually reading the overlay section. For a more user-friendly approach, use the dtoverlay command to list active overlays after boot:

dtoverlay -l

This shows which overlays are loaded, but not the pin details. To see the actual GPIO assignments, you can inspect the overlay source files in /boot/overlays/ (on Raspberry Pi OS) or in the kernel source on GitHub. For example, the overlay for the Adafruit 1.8″ TFT uses GPIO 25 for the chip select, GPIO 24 for the DC pin, and GPIO 23 for the reset. If another HAT also uses GPIO 25, you have a conflict.

Method 2: Compare Documentation and Schematics

Before buying or stacking HATs, the most reliable method is to read the product documentation. Most reputable HAT manufacturers provide a pinout diagram or a table listing the GPIO pins used. Look for phrases like “Uses GPIO 2, 3, 4, 17” or “I2C on pins 3 and 5.”

Create a simple spreadsheet with the pins used by each HAT. Mark any pin that appears in both lists. Common conflict points include:

• I2C pins (GPIO 2 and 3) – many HATs use I2C for sensors or EEPROMs, but only one can own the bus at a time unless they are designed to share.
• SPI pins (GPIO 7, 8, 9, 10, 11) – SPI devices can share the bus if they have separate chip selects, but if two HATs both use the same chip select pin, they will conflict.
• UART pins (GPIO 14 and 15) – typically used for serial communication; two HATs cannot both use UART0 without a mux.
• PWM pins (GPIO 12, 13, 18, 19) – often used for servos or LEDs; if both HATs drive the same pin, you get contention.

For example, a motor HAT might use GPIO 12, 13, 18, and 19 for PWM. A servo HAT might also use GPIO 18. Stacking them would cause a conflict on GPIO 18.

Method 3: Use Software Tools to Detect Conflicts

On a running system, you can check which GPIOs are already claimed by the kernel. The gpioinfo command (part of libgpiod) shows the state of every GPIO line:

sudo apt install gpiod
sudo gpioinfo

This lists each GPIO and its current consumer (the driver or overlay that claimed it). If you see two consumers on the same line, that’s a conflict. However, this only works after the overlays have been applied; if one overlay fails to load, the pin might appear free even though the HAT needs it.

Another approach is to use dtoverlay to test loading an overlay manually. For example, if you suspect a conflict with an overlay named myhat, you can try:

sudo dtoverlay myhat

If it fails, the kernel will output an error message like gpio_request: gpio 18 already in use. This tells you exactly which pin is conflicting.

Common Problems and Misconceptions

One common misconception is that all HATs are automatically compatible because they follow the HAT standard. The standard only defines the physical form and the EEPROM protocol; it does not guarantee that two HATs will not use the same GPIO. In fact, many HATs use the same default pins for common interfaces like I2C or SPI, so conflicts are more the rule than the exception.

Another issue is that some HATs do not have an EEPROM at all. These are often called “non-HAT” or “proto HATs.” They rely on the user to manually load a device tree overlay or to use a library like RPi.GPIO. For these, you must check the documentation and manually avoid pin conflicts.

A third problem is that some HATs use the same physical pin for different functions depending on a jumper or a software setting. For example, a HAT might use GPIO 4 as an input for a button by default, but a jumper can change it to an output for an LED. Always check the actual configuration you are using.

How to Resolve a Pin Conflict

If you find a conflict, you have several options:

• Use a different GPIO – if the HAT allows you to reconfigure its pins (e.g., via jumpers or a device tree parameter), change one HAT to use a free pin.
• Use a multiplexer – for I2C or SPI, you can use a hardware multiplexer to share the bus between devices, but this requires additional wiring and software.
• Stack with a different HAT – sometimes the simplest solution is to choose a different HAT that uses different pins.
• Use a non-stacked connection – connect one HAT via a ribbon cable or jumper wires to a different set of GPIOs, bypassing the stacking header.

For example, if two HATs both need GPIO 2 and 3 for I2C, you could use an I2C mux like the TCA9548A to create multiple I2C buses. Alternatively, you could connect one HAT’s I2C pins to a different I2C bus if your Pi has one (e.g., the secondary I2C on GPIO 0 and 1, but those are usually reserved for the EEPROM).

Frequently Asked Questions

Can I stack any two HATs on a Raspberry Pi?

No, not without checking. Stacking two HATs that use the same GPIO pins will cause conflicts. Always compare the pin usage before stacking.

How do I know which GPIO pins a HAT uses?

Check the HAT’s datasheet or product page. Most manufacturers provide a pinout table. You can also read the EEPROM overlay or use gpioinfo after boot to see which pins are claimed.

What happens if two HATs share a GPIO pin?

Depending on the functions, the Pi may boot with errors, one HAT may be non-functional, or you could damage the GPIO if both HATs drive the pin in opposite directions. It’s best to avoid conflicts entirely.

Can I use a HAT without an EEPROM?

Yes, but you must manually load the appropriate device tree overlay or configure the pins in software. The HAT standard is not mandatory for all add-on boards.

Is there a tool that automatically checks HAT compatibility?

There is no official tool that scans two HATs and tells you if they conflict. You must compare pin usage manually. Some third-party tools exist, but they are not standardized.

Can I change the GPIO pins a HAT uses?

Sometimes. Many HATs have jumpers or solder bridges to select alternate pins. Others allow you to override the device tree overlay parameters. Check the HAT’s documentation for options.

Final Thoughts

Checking for GPIO conflicts between stacked HATs is a matter of careful comparison. The EEPROM system helps automate configuration, but it does not prevent conflicts. By reading documentation, inspecting overlays, and using tools like gpioinfo, you can identify and resolve conflicts before they cause problems. Always power down your Pi before adding or removing HATs, and double-check your pin assignments to avoid damage.

Related

• Valor Mortis Alternatives for Parry-Focused Combat
• Pixel 10 Pro 60Hz vs 120Hz: Which Refresh Rate Setting Should You Use?
• Expandable Housing & Faster Project Delivery