Hyperpixel 2.1 Round Touch Display

Setup a Hyperpixel 2.1 Round Display with touch controller mounted on a Raspberry Zero or Raspberry Zero 2. This page shows how display drivers are installed for using touchpi.
We accept no liability for any problems that may arise when following this procedure.

Note

Pimoroni states that the installation is best done with Raspberry OS Buster. However, the end of support is already in June 2024, but the installation routine has worked on all Raspberry OS versions so far. On Bullseye and Bookworm, the /boot/config.txt file still needs to be adjusted a little bit. The rotation script hyperpixel2r-rotate does not work with a Buster lite installation and generally not on Bullseye or Bookworm. However, the screen rotation can be set manually so that the screen can also be used with touchpi.

Install Image

It is a good idea to save some system files after installation and first boot. Image installation is described here: Installation. First boot can last several minutes until the device gets an IP from your DHCP Server (sometime the initial boot can hang. In this rare cases just disconnect from power and try again. Or burn image again). login with an ssh terminal (e.g. putty) and your user after the device is available in your LAN (if ssh is used don’t forget to add your ssh private key in the ssh terminal configuration).

Update OS

sudo apt update && sudo apt upgrade --yes
sudo apt install --yes --no-install-recommends git xorg x11-apps xinput-calibrator
sudo apt autoremove --yes

Note

This can last up to 15 minutes for a pi zero and a buster os

Install Display Driver

Install Driver:

git clone https://github.com/pimoroni/hyperpixel2r

cd hyperpixel2r

sudo ./install.sh

Display documentation: Github pimoroni/hyperpixel2r.

Changes in /boot/config.txt

sudo nano /boot/config.txt

add the line display_rotate=0 at the end of the file.

Uncomment other dtoverlay driver like dtoverlay=vc4-kms-v3d, if not allready uncommented.

Uncomment these config entries (existence is dependend of the Raspberry OS version): max_framebuffers , display_auto_detect , disable_fw_kms_setup

/boot/cmdline.txt of a Raspberry OS Buster

# 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 this if your display has a black border of unused pixels visible
# and your display can output without overscan
#disable_overscan=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

[pi4]
# Enable DRM VC4 V3D driver on top of the dispmanx display stack
# dtoverlay=vc4-fkms-v3d
# max_framebuffers=2

[all]
# dtoverlay=vc4-fkms-v3d

dtoverlay=hyperpixel2r
enable_dpi_lcd=1
dpi_group=2
dpi_mode=87
dpi_output_format=0x7f216
dpi_timings=480 0 10 16 55 480 0 15 60 15 0 0 0 60 0 19200000 6
display_rotate=0

/boot/cmdline.txt of a Raspberry OS Bookworm

...

# Automatically load overlays for detected DSI displays
# display_auto_detect=1

# Automatically load initramfs files, if found
auto_initramfs=1

# Enable DRM VC4 V3D driver
# dtoverlay=vc4-kms-v3d
# max_framebuffers=2

# Don't have the firmware create an initial video= setting in cmdline.txt.
# Use the kernel's default instead.
# disable_fw_kms_setup=1

# Disable compensation for displays with overscan
disable_overscan=1

# Run as fast as firmware / board allows
arm_boost=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]
dtoverlay=hyperpixel2r
enable_dpi_lcd=1
dpi_group=2
dpi_mode=87
dpi_output_format=0x7f216
dpi_timings=480 0 10 16 55 480 0 15 60 15 0 0 0 60 0 19200000 6
display_rotate=0

Reboot with sudo shutdown -r now or simply sudo reboot

Note

Running software on a pi zero with Bookworm (not on a pi zero 2) feels subjectively somewhat slower than with buster or bullseye.

Rotation (screen and touch)

Manufacturer script hyperpixel2r-rotate does not work with Buster lite or any Bullseye or any Bookworm. For rotation change the /boot/config.txt file and the /usr/share/X11/xorg.conf.d/40-libinput.conf file manually.

Edit with sudo nano.

/boot/config.txt	/usr/share/X11/xorg.conf.d/40-libinput.conf
display_rotate=0 USB on bottom Option is optional.	Option "TransformationMatrix" "1 0 0 0 1 0 0 0 1" Option is optional. Not needed in the file.
90° (left): display_rotate=1 USB on the right side	Use TransformationMatrix 90 -> Option "TransformationMatrix" "0 1 0 -1 0 1 0 0 1"
180° (upside down): display_rotate=2 USB on top	Use TransformationMatrix 180 -> Option "TransformationMatrix" "-1 0 1 0 -1 1 0 0 1"
90° (right): display_rotate=3 USB on the left side	Use TransformationMatrix 270 -> Option "TransformationMatrix" "0 -1 1 1 0 0 0 0 1"

The /usr/share/X11/xorg.conf.d/40-libinput.conf file can look like this example with a 90° rotation of the touch input

Changed /usr/share/X11/xorg.conf.d/40-libinput.conf

# Match on all types of devices but joysticks
#
# If you want to configure your devices, do not copy this file.
# Instead, use a config snippet that contains something like this:
#
# Section "InputClass"
#   Identifier "something or other"
#   MatchDriver "libinput"
#
#   MatchIsTouchpad "on"
#   ... other Match directives ...
#   Option "someoption" "value"
# EndSection
#
# This applies the option any libinput device also matched by the other
# directives. See the xorg.conf(5) man page for more info on
# matching devices.

Section "InputClass"
        Identifier "libinput pointer catchall"
        MatchIsPointer "on"
        MatchDevicePath "/dev/input/event*"
        Driver "libinput"
EndSection

Section "InputClass"
        Identifier "libinput keyboard catchall"
        MatchIsKeyboard "on"
        MatchDevicePath "/dev/input/event*"
        Driver "libinput"
EndSection

Section "InputClass"
        Identifier "libinput touchpad catchall"
        MatchIsTouchpad "on"
        MatchDevicePath "/dev/input/event*"
        Driver "libinput"
EndSection

Section "InputClass"
        Identifier "libinput touchscreen catchall"
        MatchIsTouchscreen "on"
        Option "TransformationMatrix" "0 1 0 -1 0 1 0 0 1"
        MatchDevicePath "/dev/input/event*"
        Driver "libinput"
EndSection

Section "InputClass"
        Identifier "libinput tablet catchall"
        MatchIsTablet "on"
        MatchDevicePath "/dev/input/event*"
        Driver "libinput"
EndSection

Read more about offsets, scaling and rotation here.

Test X window server

run X window server in background:

sudo -b /usr/lib/xorg/Xorg :0

Run xcalc with DISPLAY=:0.0 xcalc -geometry 340x340-70+70

A calculator should be displayed and touch events should work.