HyperPixel 4.0 is an 800x480 or 720x720 pixel DPI display for Raspberry Pi, with optional capacitive touchscreen. The drivers/instructions in this repo are written for and tested with Raspberry Pi OS, and are not guaranteed to work with other operating systems.
Raspberry Pi OS Bullseye includes major changes to how DPI display drivers work. If you're using an image dated 04/04/2022 or later, it will come with Hyperpixel drivers baked in and you don't need to run the legacy installer. You can set up display and touch by adding a few lines to your boot/config.txt:
PSA: HyperPixel 4 (Square & Rectangular) on Raspberry Pi OS 2022-04-04
This repository contains several branches for different combinations of Pi and HyperPixel4 boards.
You should use our one-line installer to install HyperPixel4 Rectangular and Square:
curl -sSL https://get.pimoroni.com/hyperpixel4 | bash
When prompted, pick the combination of Pi and touchscreen that you're planning to use.
Note: A HyperPixel4 setup for Pi 3B+ or earlier will not readily work if you move it over to a Pi 4, you should run this installer again to update the drivers.
Here's a list of active branches and which Pi/display combination they support:
- pi3 - Pi 3B+ and earlier, HyperPixel4 Rectangular
- pi4 - Pi 4 & Pi 400, HyperPixel4 Rectangular, use
hyperpixel4-rotateto rotate once installed - square - Pi 3B+ and earlier, HyperPixel4 Square (for boards manufactured 2020 and earlier)
- square-pi4 - Pi 4 & Pi 400, HyperPixel4 Square (for boards manufactured 2020 and earlier)
- square-2021 - Pi 3B+ and earlier, HyperPixel4 Square (for boards manufactured 2021 and later)
- square-pi4-2021 - Pi 4 & Pi 400, HyperPixel4 Square (for boards manufactured 2021 and later)
To clone a specific branch to your Pi, run:
git clone https://github.com/pimoroni/hyperpixel4 -b <branch name>
Then cd hyperpixel4 and run sudo ./install.sh to install it.
HyperPixel4 is a portait display, so on first boot it will start in portrait mode with the USB ports at the top.
On Pi 4 we can take advantage of the rotation available in Display Configuration, and provide you with a command for setting both display and touch rotation together.
To rotate HyperPixel4 on a Pi 4 use the hyperpixel4-rotate command.
Landscape mode, HDMI/power ports on the bottom:
hyperpixel4-rotate left
Landscape mode, HDMI/power ports on the top:
hyperpixel4-rotate right
Portrait mode, USB ports on the top:
hyperpixel4-rotate normal
Portrait mode, USB ports on the bottom:
hyperpixel4-rotate inverted
If you're running this command over SSH you should prefix it with DISPLAY=:0.0
Note: You must build the latest dtoverlay file to enable rotation support:
- Go into
src - run
maketo build a new hyperpixel4.dtbo with rotation support - copy the overlay with
sudo cp hyperpixel4.dtbo /boot/overlays/
To rotate your HyperPixel4 you must edit /boot/config.txt and change the following lines:
- Change
dtoverlay=hyperpixel4todtoverlay=hyperpixel4:rotate - Change
display_rotate=3todisplay_rotate=1
This will rotate both the display and the touchscreen input to match.
If you're using a non-touchscreen HyperPixel4 you need only change display_rotate.
dtoverlay=vc4-fkms-v3d in /boot/config.txt
You can use xrandr and xinput to rotate the display and touchscreen in turn.
For HyperPixel Square, substitute the device name with "pointer:generic ft5x06 (11)".
DISPLAY=:0.0 xrandr --output DSI-1 --rotate left
DISPLAY=:0.0 xinput set-prop "pointer:Goodix Capacitive TouchScreen" "libinput Calibration Matrix" 0 -1 1 1 0 0 0 0 1
DISPLAY=:0.0 xrandr --output DSI-1 --rotate right
DISPLAY=:0.0 xinput set-prop "pointer:Goodix Capacitive TouchScreen" "libinput Calibration Matrix" 0 1 0 -1 0 1 0 0 1
DISPLAY=:0.0 xrandr --output DSI-1 --rotate normal
DISPLAY=:0.0 xinput set-prop "pointer:Goodix Capacitive TouchScreen" "libinput Calibration Matrix" 1 0 0 0 1 0 0 0 1
DISPLAY=:0.0 xrandr --output DSI-1 --rotate inverted
DISPLAY=:0.0 xinput set-prop "pointer:Goodix Capacitive TouchScreen" "libinput Calibration Matrix" -1 0 1 0 -1 1 0 0 1
Add the relevant settings from above into /usr/share/X11/xorg.conf.d/88-hyperpixel4.conf.
You will need the device name:
- "Goodix Capacitive TouchScreen" for HyperPixel 4 Rectangular
- "generic ft5x06 (11)" for HyperPixel 4 Square
And the 9 numbers from the "Calibration Matrix", eg: -1 0 1 0 -1 1 0 0 1
Plus the rotation direction for the monitor.
Section "InputClass"
Identifier "libinput HyperPixel4 Rectangular"
MatchProduct "Goodix Capacitive TouchScreen"
Option "CalibrationMatrix" "0 -1 1 1 0 0 0 0 1"
EndSection
Section "Monitor"
Identifier "DSI-1"
Option "Rotate" "left"
EndSection
If you're using lightdm (the default window manager on Raspberry Pi OS) and it's calling /usr/share/dispsetup.sh you'll need to either disable that call in /etc/lightdm/lightdm.conf or change dispsetup.sh to just exit 0. Removing dispsetup.sh will break lightdm and boot you to a black screen of death.
⚠️ Running "Screen Configuration" will re-createdispsetup.shand override your Xorg settings⚠️ Removingdispsetup.shfrom/etc/lightdm/lightdm.confwill prevent "Screen Configuration" settings for persisting.- You should probably use
hyperpixel4-rotateunless you really know what you're doing!
Where possible we are collecting known FAQs under the notice label in our issue tracker.
If your issue is not covered by one of these provided by our team and community then we ask you to provide some debugging information using the following oneliner:
curl -sSL https://raw.githubusercontent.com/pimoroni/hyperpixel4/master/hyperpixel4-debug.sh | bashThen file a bug report.
