From Fedora Project Wiki
(15 intermediate revisions by 3 users not shown)
Line 1: Line 1:
 
= Raspberry Pi HATs =
 
= Raspberry Pi HATs =
This page will be used to document using various HATs on the Raspberry Pi. Please feel free to add notes pertaining to other HATs or additions to the existing entries.  
+
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.
  
== Sense Hat ==
+
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.
  
Remove the symlink for the dtb:
+
== General Status ==
rm /boot/efi/dtb
+
To switch from the "[https://www.kernel.org/doc/html/latest/devicetree/index.html kernel device tree]" to the "[https://www.raspberrypi.org/documentation/configuration/device-tree.md 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 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
 
Edit the '/boot/efi/config.txt' to add the overlay
 
  dtoverlay=rpi-sense
 
  dtoverlay=rpi-sense
  
 
==== Working ====
 
==== Working ====
* Humidity Sensor
+
* Humidity Sensor (hts221)
* Magnetometer
+
* Barometer (lps25h)
 +
* Magnetometer (lsm9ds1_magn)
 +
* Temperature (hts221, lps25h)
  
 
==== Not Working ====
 
==== Not Working ====
 +
* 8x8 LED matrix display
 +
* Small 5 button joystick
  
== Adafruit PiTFT Plus (3.5 inch Resistive Touch screen) ==
+
=== Adafruit PiTFT Plus (3.5 inch Resistive Touch screen) ===
 
To use the screen you will need to install 'bcm283x-firmware-20191118-1.68ec481.fc31' or later. To use the touch features of the screen you also need to install 'kernel-5.4.0-0.rc8.git0.1.fc32' or later.
 
To use the screen you will need to install 'bcm283x-firmware-20191118-1.68ec481.fc31' or later. To use the touch features of the screen you also need to install 'kernel-5.4.0-0.rc8.git0.1.fc32' or later.
 
Remove the symlink for the dtb:
 
rm /boot/efi/dtb
 
  
 
Edit the '/boot/efi/config.txt' to add the overlay
 
Edit the '/boot/efi/config.txt' to add the overlay
 
  dtparam=i2c_arm=on
 
  dtparam=i2c_arm=on
dtparam=spi=on
 
 
  dtoverlay=pitft35-resistive
 
  dtoverlay=pitft35-resistive
 
  hdmi_force_hotplug=1
 
  hdmi_force_hotplug=1
Line 40: Line 62:
 
To workaround the bug and have it load automatically use:
 
To workaround the bug and have it load automatically use:
 
  echo hx8357d >> /etc/modules-load.d/hx8357d.conf
 
  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.

Revision as of 00:23, 15 February 2021

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 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)

To use the screen you will need to install 'bcm283x-firmware-20191118-1.68ec481.fc31' or later. To use the touch features of the screen you also need to install 'kernel-5.4.0-0.rc8.git0.1.fc32' or later.

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

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

Add to the kernel parameters

fbcon=map:10 fbcon=font:ProFont6x11

Due to a bug the kernel module will not load automatically. On boot the module can be loaded with:

modprobe hx8357d

Due to a bug with the VC4 driver you will also need to blacklist it:

echo "blacklist vc4" >> /etc/modprobe.d/blacklist-vc4.conf

To workaround the bug and have it load automatically use:

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.