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

Serial devices

Raspberry Pis up to but not including the 4-series have only one UART which is UART0/1 (depending on which chip you use).

On Fedora Linux the UART0/1 is first setup and controlled by uboot to expose a serial console with boot log information. After that the initramfs will take over and eventually the kernel / operating system. Fedora Linux does not use it as console by default.

Activate UART0/1 with the following overlay configuration in /boot/efi/config.txt:

dtoverlay=uart0

UART0/1 can be configured to use a different GPIO mapping. Available PINs for this purpose are 14/15, 32/33, 36/37.

dtoverlay=uart0,txd0_pin=32,rxd0_pin=33

Deactivate Serial Console entirely

Although Fedora Linux does not use UART0/1 as console the uboot bootloader does. In order to use UART0/1 as serial device through the whole boot cycle the usage in uboot has to be disabled. To do this you have two options:

• Connect keyboard and display to the device and disable console usage manually in the uboot configuration menu
• Build and deploy a uboot with the console disabled

Activate Serial Console in Fedora Linux

Configure the serial console in Fedora Linux by enabling the UART0 overlay and set the kernel parameters to use it to print the system log.

On Fedora IoT and other RPM-OSTree distributions change the kernel parameters through:

$ rpm-ostree kargs --append-if-missing=console=ttyAMA0,115200

Use hardware UART for UART0/1

Per default since Raspberry Pi 3 the UART0/1 are implemented in software which might not suit your needs. It is possible however to set the UART0/1 to use hardware instead. In order to do this however you'll have to either disable bluetooth or switch it such that bluetooth will now use the software UART for it's operation which might introduce bluetooth connection problems.

Disable bluetooth entirely. UART0/1 will automatically use hardware:

dtoverlay=pi3-disable-bt

Switch bluetooth and UART0/1 over:

dtoverlay=pi3-miniuart-bt

Raspberry Pi 4 and BCM2711

The Raspberry Pi 4, Raspberry Pi 400 and CM4 generation of Raspberry Pi devices features a the new BCM2711 chip and exposes multiple UARTs or serial devices on the pin out.

Each of these devices can be activated and linked to GPIOs through overlays. There are in total 5 UARTs available:

• UART0/1 is the same as on the other boards
• UART2 GPIOs 0 - 3
• UART3 GPIOs 4 - 7
• UART4 GPIOs 8 - 11 (is in conflict with the TPM overlay)
• UART5 GPIOs 12 - 15

Activate the UARTs by adding the following line to /boot/efi/config.txt:

dtoverlay=uart2

The new devices will appear as /dev/ttyAMA0-4. Note that the numbering is simply counting through the activated devices. The numbers are not linked to any UART specifically. Only activating UART0 and UART5 will make UART5 be available as /dev/ttyAMA1.

Each of the additional overlays can be configured to also use hardware flow control or the CTS/RTS mechanics. In order to activate you have to provide the following in /boot/efi/config.txt

dtoverlay=uart2,crtscts

Note: Raspberry Pi Foundation engineering states that the CTS/RTS lines are inverted (nCTS/nRTS) and that for transmission the driver expects CTS to be actively pulled low. This is not really well documented.

In order to use hardware flow control you not only have to activate it in the overlay but also instruct the device to use it. E.g. with tools like stty.

$ stty -F /dev/ttyAMA1 crtscts

Details for specific HATs

RTC HAT

The RTC HATs work with the upstream kernel rtc_ds1307 driver. You will need to know the specific RTC chip that your HAT using.

A full list of supported RTC chips can be found in /boot/efi/overlays/README in the i2c-rtc section.

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

For the DS3231:

dtoverlay=i2c-rtc,ds3231

PoE Hat

The PoE HATs works with the upstream kernel drivers but you need at least firmware 20220209-1.577aef2 to specify i2c to run the device control from Linux rather than the RPi firmware.

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

For the original PoE HAT:

dtoverlay=rpi-poe,i2c

For the PoE+ HAT:

dtoverlay=rpi-poe-plus,i2c

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 Libera.chat channel #fedora-arm.