PSA: HyperPixel 4 (Square & Rectangular) on Raspberry Pi OS 64bit 2022-04-04

[Gadgetoid]

:information_source: See this comment for rotation in Raspberry Pi Desktop screen configuration - https://github.com/pimoroni/hyperpixel4/issues/177#issuecomment-1786957639

:warning: PSA: Make sure you disable i2c, SPI and any other interfaces since these will cause a conflict in device-tree with HyperPixel :warning:

:warning: A fresh image is recommended, but otherwise make sure you also disable the hyperpixel4-init system service! :warning:

Pi 3B and Pi 4 users running the latest and greatest Raspberry Pi OS should forego our installer and use the instructions below.

:information_source: If you're tied to an older OS and you want to install the legacy drivers, use: curl -sSL get.pimoroni.com/hyperpixel4-legacy | bash

This new OS can currently be found in Raspberry Pi Imager under "Raspberry Pi OS (Other)"

Once installed you need only one line in /boot/config.txt:

• Rectangular: dtoverlay=vc4-kms-dpi-hyperpixel4
• Square: dtoverlay=vc4-kms-dpi-hyperpixel4sq

You can rotate these in config.txt by adding the rotate= parameter, like so:

dtoverlay=vc4-kms-dpi-hyperpixel4sq,rotate=90

This supports rotation in console, too, for all you CyberDeck builders!

HyperPixel 4 Rectangular Rotations

Ensure rotation is set to "Normal" in "Display Configuration"

And that the dtoverlay is in /boot/config.txt:

dtoverlay=vc4-kms-dpi-hyperpixel4

Finally use one of the following dtparam lines immediately underneath to set the parameters:

• The default is portrait with header on the right, no extra line needed
• dtparam=rotate=90,touchscreen-swapped-x-y,touchscreen-inverted-y - Landscape with header on the bottom
• dtparam=rotate=180 - Portrait with header on the left
• dtparam=rotate=270,touchscreen-swapped-x-y,touchscreen-inverted-x - Landscape with header on the top

HyperPixel 4 Square Rotations

HyperPixel 4 Square does not correctly swap or invert touch input, so you may want to use the Xorg config method below.

Ensure rotation is set to "Normal" in "Display Configuration"

And that the dtoverlay is in /boot/config.txt:

dtoverlay=vc4-kms-dpi-hyperpixel4sq

Finally use one of the following dtparam lines immediately underneath to set the parameters:

• Default is header on the top
• dtparam=rotate=90 - Header is on the left (wonky touch, see below)
• dtparam=rotate=180 - Header still on the top (doesn't work? Same as default)
• dtparam=rotate=270 - Header is on the right (wonky touch, see below)

:warning: The touchscreen-swapped-x-y parameter does not seem to work with Square. You may need to use the script below for Raspberry Pi OS with Desktop.

On the fly rotation

Rotating the display via "Screen Configuration" ("arandr") results in inverted touch input and other weirdness- use the dtoverlay params.

If you want to rotate on the fly you can use the below bash script to rotate either display and persist settings into Xorg configuration files.

:warning: Note: You must remove the rotate= argument from /boot/config.txt for these to make sense.

You can remove the rotation config by deleting the /usr/share/X11/xorg.conf.d/88-hyperpixel4-touch.conf and /usr/share/X11/xorg.conf.d/88-dsi-1-rotate.conf files.

#!/bin/bash

UTILITY="hyperpixel4-rotate (Rectangular)"
XORG_TOUCH_CONF_FILE="/usr/share/X11/xorg.conf.d/88-hyperpixel4-touch.conf"
XORG_CONF_FILE="/usr/share/X11/xorg.conf.d/88-dsi-1-rotate.conf"

OVERLAY_S="vc4-kms-dpi-hyperpixel4sq"
OVERLAY_R="vc4-kms-dpi-hyperpixel4"

function success() {
    echo -e "$(tput setaf 2)$1$(tput sgr0)"
}

function inform() {
    echo -e "$(tput setaf 6)$1$(tput sgr0)"
}

function warning() {
    echo -e "$(tput setaf 1)$1$(tput sgr0)"
}

function set_xorg_conf {
    if [ "$DISPLAY" == "" ]; then
        inform "No DISPLAY variable set, trying :0.0"
        export DISPLAY=:0.0
    fi

    inform "Rotating display $1";
    xrandr --output DPI-1 --rotate $1

    MATRIX="$2 $3 $4 $5 $6 $7 $8 $9 ${10}"

    inform "Setting libinput Calibration Matrix: 1 0 0 0 1 0";
    xinput set-prop "pointer:$DEVICE" "libinput Calibration Matrix" 1 0 0 0 1 0 0 0 1

    inform "Setting Coordinate Transformation Matrix: $MATRIX";
    xinput set-prop "pointer:$DEVICE" "Coordinate Transformation Matrix" $MATRIX

    inform "Saving xorg touch config to $XORG_TOUCH_CONF_FILE";
    sudo tee $XORG_TOUCH_CONF_FILE > /dev/null <<EOF
# Auto generated by $UTILITY, edit with care!

Section "InputClass"
    Identifier "HyperPixel4 $DEVICE"
    MatchProduct "$DEVICE"
    Option "CalibrationMatrix" "1 0 0 0 1 0 0 0 1"
    Option "TransformationMatrix" "$MATRIX"
EndSection
EOF

    inform "Saving xorg rotate config to $XORG_CONF_FILE";
    sudo tee $XORG_CONF_FILE > /dev/null <<EOF
# Auto generated by $UTILITY, edit with care!

Section "Monitor"
    Identifier "DPI-1"
    Option "Rotate" "$1"
EndSection
EOF
}

printf "HyperPixel 4: Display & Touch Rotation\n"
printf "This utility requires the Raspberry Pi OS desktop or an *Xorg-based* alternative.\n\n"

ORIENTATION=$1

grep -e "^dtoverlay=$OVERLAY_S.*" /boot/config.txt > /dev/null
if [ $? -ne 0 ]; then
    grep -e "^dtoverlay=$OVERLAY_R.*" /boot/config.txt > /dev/null
    if [ $? -ne 0 ]; then
        warning "Rotation requires hardware support on the Pi 4 or Pi 400"
        warning "Ensure your HyperPixel4 is enabled in /boot/config.txt"
	printf "\nSquare:      dtoverlay=$OVERLAY_S\n"
	printf "Rectangular: dtoverlay=$OVERLAY_R\n\n"
        exit 1
    else
        inform "Detected HyperPixel 4 Rectangular (found \"$OVERLAY_R\" in config.txt)"
        DEVICE="Goodix Capacitive TouchScreen"
    fi
else
    inform "Detected HyperPixel 4 Square (found \"$OVERLAY_S\" in config.txt)"
    DEVICE="EP0110M09"
fi

case $ORIENTATION in
    "right")
        set_xorg_conf $ORIENTATION 0 1 0 -1 0 1 0 0 1
        ;;
    "left")
        set_xorg_conf $ORIENTATION 0 -1 1 1 0 0 0 0 1
        ;;
    "inverted")
        set_xorg_conf $ORIENTATION -1 0 1 0 -1 1 0 0 1
        ;;
    "normal")
        set_xorg_conf $ORIENTATION 1 0 0 0 1 0 0 0 1
        ;;
    *)
        printf "Unsupported orientation: $ORIENTATION\n\n";
        printf "Usage:\n"
        printf "    $0 <orientation>\n\n"
        printf "Where orientation is one of: left, right, normal, inverted.\n"
        exit 1
esac

[e28eta]

This is almost working for me: it only works in the non-rotated orientation on boot.

I bought my HyperPixel 4 Rectangular a month ago to use with a Pi 400 & Adafruit’s Cyberdeck HAT. I removed the diode on the HAT, and then ran into a black screen (backlight but no picture), and found some of the issues linked above. I was really happy to see this update.

With only dtoverlay=vc4-kms-dpi-hyperpixel4 in /boot/config.txt it’ll boot and display, albeit rotated 90° clockwise. This is working well, as far as I can tell.

If I try to use either ,rotate=270 appended to the dtoverlay line or the separate dtparam line that includes the touchscreen options, the display doesn’t work.

If I remove the rotation settings from /boot/config.txt and try to use the embedded script (xrandr, etc), it works on that particular session. When I reboot, it breaks.

The failure looks like either a black screen, or a screen where one pixel (the first??) in each row is repeated all the way across the screen (the latter seems to be more common, but I’m not sure). I haven’t been able to determine when each behavior is triggered.

I’ve been trying both with an HDMI monitor connected, and also with only the hyperpixel (aka DP1) and changing config over ssh. There may be behavior differences, but neither setup is working correctly.

Is there helpful information I can gather, either for this issue or to file a new one? Sometimes, but not always, there’s a register + call trace dump visible inside of dmesg output, related to the goodix_ts_driver. I’ve captured several sets of dmesg logs, but didn’t keep any notes on what the particulars of each were 😞

[Gadgetoid]

Could you paste the lines you have in your config.txt when you're trying to get rotation work? Would help me to recreate.

[Gadgetoid]

Weird, same config and same SD card in my Pi 3B+ versus my Pi 4 results in two different rotations...

:scream:

Edit (For posterity and to nobody in particular):

I have a suspicion that "/usr/share/dispsetup.sh" did this. It's the script that gets updated by Screen Configuration (arandr) and then run on boot via lightdm.conf.

There's also a .config/monitors.xml ~which I guess used by Mutter on Pi 4? Screen Configuration also updates this file, but manually editing it to different rotations doesn't seem to affect my display setup.~ which is for Gnome and unrelated to the Pi config afaict.

And any touch or rotation dropped into /usr/share/X11/xorg.conf.d/ can potentially cause issues, too.

[e28eta]

I've tried three different /boot/config.txt variations. Full contents, summary of changes from default:

dtoverlay=vc4-kms-dpi-hyperpixel4

dtoverlay=vc4-kms-dpi-hyperpixel4,rotate=270

dtoverlay=vc4-kms-dpi-hyperpixel4
dtparam=rotate=270,touchscreen-swapped-x-y,touchscreen-inverted-x

I have an (occasionally) working setup with the first one (no parameters to the overlay), and having run the bash script you provided :tada: After having ran that bash script, I haven't deleted / reset those settings to go back to a dtoverly + dtparam only solution.

---

Unfortunately, sometimes it fails. I thought the failure was deterministic, but I don't think that's true. I've seen three different failure modes:

• A black screen. The backlight is on and the OS knows a display is connected, but nothing is being drawn.
• One pixel repeated all the way across the screen, maybe skipping every other column? Here's a brief video, in which I move the mouse, and then touch & drag (and the selection rectangle it should be displaying also causes colors to change):

https://user-images.githubusercontent.com/483223/163491202-71712123-d062-48cb-a151-4d862a1ac00c.mov

• every other (I think?) column is skipped, and it throws off the locations of touches:

https://user-images.githubusercontent.com/483223/163491325-d370a209-8a0c-4119-8b9e-71c9281c9d7b.mov

• initially I was also trying to get multi-monitor to work (mostly so I had an attached display I could use while fiddling with the hyperpixel4). I observed touches on the hyperpixel being interpreted as happening within the bounds of the HDMI display

---

I have seen all three display failure modes in each of these cases:

• on a cold boot (as usb-c cable initially plugged in), a software-based reboot (command line or GUI), and a boot using the pi400 power key (after a software-based shutdown command)
• with multiple monitors, with the hyperpixel as the primary and not the primary (configured through arandr since I don't know xrandr well).
• with only the hyperpixel plugged in (I've done most of my testing like this)

I haven't figured if there's a configuration/sequence that always fails, nor do I know if one is more likely to succeed. ex: I thought cold boot was pretty reliable yesterday, but so far today it's failed 3 out of 4 times. Similarly, my initial assertion that it only worked non-rotated on cold boot could have just been random good luck across 3-4 attempts.

---

Here's an example of the Goodix-TS failure logs from dmesg: dmesg-goodix-failure.txt

My guess is that the TS is for touch screen. I don't know if this is a red herring / unrelated. It's not always there when the display fails to work.

---

Late additions:

• the screen is inverted in the horizontal direction:

• inverted with some columns missing:

• looks like every other column is white instead of black?

---

environment: Pi 400

$ uname -a
Linux pi400 5.15.32-v8+ #1538 SMP PREEMPT Thu Mar 31 19:40:39 BST 2022 aarch64 GNU/Linux

apt says it's fully up to date, and as far as I can remember the only significant thing I've really done with this device / SD card was run the old hyperpixel4 script. I'd be willing to wipe & re-image if you want.

[Gadgetoid]

There's a good chance the old hyperpixel script will break this in ways I can't imagine, but it should suffice to run:

sudo systemctl disable hyperpixel4-init.service

It could easily be this init script half-working that's messing up the display.

Also make sure nothing from the legacy installer is in config.txt.

A wipe and re-image is probably the safest bet though, the old installer is fundamentally a bunch of nasty hacks based around the old config.txt way of setting up DPI.

[e28eta]

There's a good chance the old hyperpixel script will break this in ways I can't imagine, but it should suffice to run:

sudo systemctl disable hyperpixel4-init.service

It could easily be this init script half-working that's messing up the display.

Also make sure nothing from the legacy installer is in config.txt.

That seems to have done it 🎉 🎊

I feel dumb/embarrassed 😞 I'd previously found and reverted the /boot/config.txt changes, and looked through the installer script for other config files that might have been changed, but didn't find the service to disable.

Thanks so much for the help!

[cubismod]

Howdy so I just installed this on a fresh OS install (April 4th 2022 64 bit on a Pi 4) and I get a blank white display. Using the square display.

[cubismod]

Nevermind! My issue was that I had removed dtoverlay=vc4-kms-v3d which caused the display to not work correctly.

[Gadgetoid]

Nevermind! My issue was that I had removed dtoverlay=vc4-kms-v3d which caused the display to not work correctly.

No worries. Useful to know exactly how this fails for future reference!

[sunsmoke]

Should this work with the 2020-and-earlier version of the hyperpixel4sq on a Pi3b+? I tried both the 64bit and 32bit builds of Bullseye, released 2022-04-04. I get what appears to be vertical stripes in both cases. It doesn't seem to matter if hdmi is connected or not. If hdmi is connected, then I get a very low resolution desktop on hdmi. Both installs are fresh, plain installs, and the only change I made was to add "dtoverlay=vc4-kms-dpi-hyperpixel4sq" to the end of /boot/config.txt

[Gadgetoid]

Should this work with the 2020-and-earlier version of the hyperpixel4sq on a Pi3b+? I tried both the 64bit and 32bit builds of Bullseye, released 2022-04-04. I get what appears to be vertical stripes in both cases. It doesn't seem to matter if hdmi is connected or not. If hdmi is connected, then I get a very low resolution desktop on hdmi. Both installs are fresh, plain installs, and the only change I made was to add "dtoverlay=vc4-kms-dpi-hyperpixel4sq" to the end of /boot/config.txt

Youch- that's a good question, to which the answer is: no. They require - iirc - very different configurations and bringup. That's something I'm going to have to look into. I had forgotten there were two flavours of Square :grimacing:

[sunsmoke]

Thanks! If you would like me to test anything, let me know.

[brotherlogic]

This new version does not work on my Pi Zero 2 W, the screen is just blank - my dtoverlay is:

dtoverlay=vc4-kms-v3d dtoverlay=vc4-kms-dpi-hyperpixel4sq

confirmed that the screen works fine on the prior install (with the script config). Is there anything else that I need to configure?

[tl8roy]

I have done a clean SD card wipe and reinstall on a Pi 400 and I am now getting a blank screen even after adding the new dto in the config.txt.

It was working on my existing installation which had the legacy drivers installed previously. I disabled the legacy service, but I also removed the old hyperpixel.dto. Once I did that and rebooted, the display stopped working. At that point I flashed the new OS to see if that would work.

This is a completely vanilla install with nothing done other than an apt update.

sudo cat /boot/config.txt
# For more options and information see
# http://rpf.io/configtxt
# Some settings may impact device functionality. See link above for details

# uncomment if you get no picture on HDMI for a default "safe" mode
#hdmi_safe=1

# uncomment the following to adjust overscan. Use positive numbers if console
# goes off screen, and negative if there is too much border
#overscan_left=16
#overscan_right=16
#overscan_top=16
#overscan_bottom=16

# uncomment to force a console size. By default it will be display's size minus
# overscan.
#framebuffer_width=1280
#framebuffer_height=720

# uncomment if hdmi display is not detected and composite is being output
#hdmi_force_hotplug=1

# uncomment to force a specific HDMI mode (this will force VGA)
#hdmi_group=1
#hdmi_mode=1

# uncomment to force a HDMI mode rather than DVI. This can make audio work in
# DMT (computer monitor) modes
#hdmi_drive=2

# uncomment to increase signal to HDMI, if you have interference, blanking, or
# no display
#config_hdmi_boost=4

# uncomment for composite PAL
#sdtv_mode=2

#uncomment to overclock the arm. 700 MHz is the default.
#arm_freq=800

# Uncomment some or all of these to enable the optional hardware interfaces
dtparam=i2c_arm=on
#dtparam=i2s=on
dtparam=spi=on

# Uncomment this to enable infrared communication.
#dtoverlay=gpio-ir,gpio_pin=17
#dtoverlay=gpio-ir-tx,gpio_pin=18

# Additional overlays and parameters are documented /boot/overlays/README

# Enable audio (loads snd_bcm2835)
dtparam=audio=on

# Automatically load overlays for detected cameras
camera_auto_detect=1

# Automatically load overlays for detected DSI displays
display_auto_detect=1

# Enable DRM VC4 V3D driver
dtoverlay=vc4-kms-v3d
max_framebuffers=2
dtoverlay=vc4-kms-dpi-hyperpixel4
#,rotate=270
#,touchscreen-swapped-x-y,touchscreen-inverted-x



# Run in 64-bit mode
arm_64bit=1

# Disable compensation for displays with overscan
disable_overscan=1

[cm4]
# Enable host mode on the 2711 built-in XHCI USB controller.
# This line should be removed if the legacy DWC2 controller is required
# (e.g. for USB device mode) or if USB support is not required.
otg_mode=1

[all]

[pi4]
# Run as fast as firmware / board allows
arm_boost=1

[all]

[tl8roy]

Top Gear Top Tip: i2c and spi both need to be commented out/disabled.

[Gadgetoid]

Top Gear Top Tip: i2c and spi both need to be commented out/disabled.

Ooof. I did not spot that. Thanks for reporting it back here!

I tend to fall into the false assumption that - like the old config.txt magic setup method did - the DPI display will trump anything else, but with device-tree it'll throw a pin conflict instead. :grimacing:

[LazLong]

Annoyingly, I had rotation working on my Pi4 with the rectangular screen. Filesystem died and I rebuilt and now it doesn't work. The difference being that I'm now running Raspian OS Lite. Do we need X to have the rotation work?

[Jeroennl]

For some reason I can't get chromium in kiosk mode to display properly (landscape), boot and without chromium is fine. I'm using a PI Zero 2 W and a rectangle screen. Any ideas what i'm missing?

[Gadgetoid]

Annoyingly, I had rotation working on my Pi4 with the rectangular screen. Filesystem died and I rebuilt and now it doesn't work. The difference being that I'm now running Raspian OS Lite. Do we need X to have the rotation work?

@LazLong Yes. Or your application must support rotation somehow. This is a frustrating consequence of RPi's move to upstream blessed methods of supporting DPI displays. You can fall back to legacy drivers and the config.txt method, but that has its own tradeoffs.

@Jeroennl as above, there's no hardware rotation in the new drivers and no config.txt setting will affect display rotation. If Kiosk mode chromium uses X under the hood you should be looking at xrandr and xorg config. See the script in my original post.

[Gadgetoid]

@brotherlogic if you haven't done a fresh install, one is highly recommended. Make sure "hyperpixel4-init" or other services aren't running at startup and breaking things.

There are also, IIRC, two versions of HyperPixel 4 Square (pre and post 2021) which are not compatible with each other. If you have an older display it's very likely these drivers don't work with it. That's something I need to follow up on.

[Jeroennl]

@Jeroennl as above, there's no hardware rotation in the new drivers and no config.txt setting will affect display rotation. If Kiosk mode chromium uses X under the hood you should be looking at xrandr and xorg config. See the script in my original post.

@Gadgetoid Fixed it using xrandr, thnx!

[Footleg]

Top Gear Top Tip: i2c and spi both need to be commented out/disabled.

Ooof. I did not spot that. Thanks for reporting it back here!

I tend to fall into the false assumption that - like the old config.txt magic setup method did - the DPI display will trump anything else, but with device-tree it'll throw a pin conflict instead. 😬

Please add this to the top of this PSA post. I just lost 2 hours trying to find out why my display apparently stopped working when I applied a rotate setting. But it was because I had also enabled i2c for the same reboot while doing initial set up from the refresh OS image. This might also be why the display did not appear to work on my original CM4 hardware stack.

[Gadgetoid]

@Footleg story of my life! Duly noted and warnings added.

[Footleg]

I can now confirm my 2019 era Hyperpixel4 rectangular with touch is working on my CM4 mounted on a Waveshare carrier board. I discovered the i2c bus mapped to 22, rather than 3 as told here https://learn.pimoroni.com/article/getting-started-with-hyperpixel-4#using-the-alternate-i2c-interface-on-hyperpixel-4-0-for-advanced-users so maybe a quick update to that article to mention you can see which bus numbers are active using the command ls /dev/i2c-* (as I learned from this comment: https://github.com/pimoroni/hyperpixel4/issues/122#issue-789137822 ).

Note that when rotating the display using the console, the touch does not map to the rotated display. It also does not map to the correct display when a second display is attached to the HDMI output either. I've not looking into options to deal with that yet, but at least I am up and running now.

[hothsolo]

After doing the instructions exactly as described here and looking thru all the comments on everything that could be wrong, I still cannot get this working. I get a black screen. Nothing else. Any ideas?

[locki-cz]

Hello, I spend few days tryed everything, and I wasnt able to make it working again, just reinstalled my some old Octoprint with octodash and want to move to mainsail klipper, also tryed all 32bit and 64bit version of great awesome Raspberry Pi OS 64bit 2022-04-04 bullseye and nothing, i can get some picture when i set dtoverlay=vc4-kms-dpi-hyperpixel4sq or some weird desktop picture after display wakeup after sleep ... just rpi console then only ugly lines :(

all what i have:

• hyperpixel4
• rpi 3b
• rpi 4b with 4gb ram
• 32gb sandisk extreme card
• original power supply Raspberry Pi USB-C 5,1V3A

I will try all to test what is wrong! Because it working before ... :(

[djbetterly]

I'm having zero luck with rotation in any direction, I've disable I2C, SPI, edited the config.txt according to the notes above and zero luck. Has anyone worked it out?

[Footleg]

I'm having zero luck with rotation in any direction, I've disable I2C, SPI, edited the config.txt according to the notes above and zero luck. Has anyone worked it out?

This worked for me as per the instructions at the top of this page with a fresh Raspberry Pi OS image (Bullseye). You do need the latest (use apt to upgrade everything if on an older Bullseye release). Check you are on Bullseye (it lists the repos being used when you run sudo apt update).

[J4CY]

Edit: I contacted Pimoroni support and was told the screen was indeed defective.

Hi all, I'm new to the HyperPixel 4.0 and RPI. I've got an RPI 4B w/ 2GB with Raspberry Pi OS 64bit bullseye installed.

Installed the screen and applied the following to /boot/config.txt.

dtoverlay=vc4-kms-dpi-hyperpixel4 
dtparam=rotate=90,touchscreen-swapped-x-y,touchscreen-inverted-y

Rotation and touch are all working as expected, but I am noticing screen tearing of some sort on this specific side of the screen. I've tried other rotations and they all seem to have the same effect. Is this expected, a software bug, or potentially a hardware issue? I've attached some videos to demonstrate my issues.

https://user-images.githubusercontent.com/89369480/173922485-b24e53d6-9450-48c5-bdc5-5938b9fe68d0.mp4

https://user-images.githubusercontent.com/89369480/173923288-7383116a-883c-4140-829a-dcfadda60476.mp4

Edit: Also gave Buster a shot and installed the drivers, screen and touch works, but still has the tearing on the same side of the screen.

[inevio-git]

I'm having zero luck with rotation in any direction, I've disable I2C, SPI, edited the config.txt according to the notes above and zero luck. Has anyone worked it out?

This worked for me as well booting into terminal. For the rotation to work in X, I had to rotate left.