Architectures/ARM/Raspberry Pi/HATs

Raspberry Pi HATs

HATs, or Hardware Attached on Top, is a means of expanding the Raspberry Pi with extra hardware based functionality. This is an overview of what we currently support, why it's supported as such, as well as some specific details on particular HATs. It's intended to be as generic as possible.

Unlike USB or PCI technologies the vast majority of hardware added to embedded systems is attached via buses where the hardware can't be discovered and self described so there needs to be a means in which to do that. The Raspberry Pi uses device tree to describe the hardware that software is expected to find, and because HATs aren't all the same, the way it allows this to be dynamic is with the use of device tree overlays.

The Raspberry Pi deals with device trees and dt overlays using the firmware which applies one or more of these overlays to the base device tree and then passes the final configuration to the kernel just before it boots. Fedora traditionally uses the device tree provided by the linux kernel as it's completely compatible with that version of the kernel and the hardware support. To enable the use of HATs and the configuration of them in the same means as used by the Raspberry Pi OS we now support a means of using "Firmware device tree" for the Raspberry Pi.

General Status

To switch from the "kernel device tree" to the "Firmware device tree" we provide a configuration option. There's a number of caveats in the way this currently works as the implementation is a minimum viable option and needs some cleaning up.

In the simplest terms if the firmware (U-Boot in this case) cannot find the kernel device tree it falls back to the firmware device tree which is provided by the RPi firmware.

While the support of HATs in general is now available by configuring config.txt just like on various Raspberry Pi OSes there may be issues with support of individual HATs in Fedora. This comes down to a number of reasons which may be specific to each HAT but is likely one of the following reasons:

• Drivers for the hardware on the HAT is not upstream (see Sense HAT details below for an example)
• The overlay for the HAT isn't upstream in Raspberry Pi firmware
• A number of the audio HATs have weird RPi drivers and should use simple audio graphs (see both points above)
• Depends on userspace drivers or random python code that just attempts to smash the HW directly via I2C/GPIO/SPI
• Uses userspace code or kernel interfaces that are insecure or have been deprecated: eg RPi.GPIO

General configuration

To use Firmware DT on a traditional Fedora, note this step isn't needed for Fedora IoT, system and hence use config.txt to configure a HAT run the following commands:

$ sudo rm /boot/dtb
$ sudo echo "FirmwareDT=True" >> /etc/u-boot.conf

The device tree symnlink won't be updated for future kernel upgrades. This will enable booting with the Firmware DT, reboot to test that it works in it's current form. From there you can edit the config.txt to enable the various dtoverlay options. It's likely useful to take backups as you change things. You can edit the file directly:

$ sudo nano /boot/efi/config.txt

Details for specific HATs

Sense Hat

Edit the '/boot/efi/config.txt' to add the overlay

dtoverlay=rpi-sense

Working

• Humidity Sensor (hts221)
• Barometer (lps25h)
• Magnetometer (lsm9ds1_magn)
• Temperature (hts221, lps25h)

Not Working

• 8x8 LED matrix display
• Small 5 button joystick

Adafruit PiTFT Plus (3.5 inch Resistive Touch screen)

Edit the '/boot/efi/config.txt' to add the overlay

dtparam=i2c_arm=on
dtoverlay=pitft35-resistive
hdmi_force_hotplug=1

For early console output add to the kernel parameters

fbcon=map:10 fbcon=font:ProFont6x11

In Fedora 34, you will need to load the module manually or upgrade to kernel-5.12.6-300 where it should load automatically.

modprobe hx8357d

To have it automatically loaded on boot with previous Fedora releases:

echo hx8357d >> /etc/modules-load.d/hx8357d.conf

Reporting bugs

Because of the complexity of kernel, device tree, overlays and firmware at the moment the easiest way to report bugs is to either the arm mailing list or to IRC on freenode channel #fedora-arm.