Getting Started with HyperPixel 4.0
In this tutorial, we'll look at how to set up and use your shiny new HyperPixel 4.0.
🚀 Note from the future: This guide was updated in May 2025 to include up to date installation instructions for the new built in kernel drivers for Hyperpixel 4.0 (Rectangular and Square variants) and Hyperpixel 2.1 (Round).
What You'll Need
- A Raspberry Pi computer - any version with a 40 pin header attached will work.
- A suitable power supply for your Pi (USB-C for newer Pi or micro USB for older Pi and Zero variants)
- A microSD card
- a keyboard, mouse, and monitor to set the software up
- a Phillips screwdriver to attach the metal standoffs to your Pi
What's In The Box
When you open your HyperPixel 4.0 box, you'll find the following:
- HyperPixel 4.0 PCB and display
- standoff kit with 4x metal standoffs and 4x screws
- female header
We'll start with how to attach your HyperPixel 4.0 to your Raspberry Pi. These instructions apply to the larger Raspberry Pi models, and we'll cover what to do with a Zero or Zero W after.
Attaching your HyperPixel 4.0 to your Raspberry Pi
Note: you should make sure your Pi is powered off for this section.
The first thing to note is that your HyperPixel 4.0 screen has a protective film on the screen. It's best to leave this on while you're attaching it, to prevent accidentally scratching the glass.
On the underside of your HyperPixel, you'll see four silver metal mounting posts that have little orange pieces of film on. Peel the pieces of film off, and then screw the threaded ends of the four black metal standoffs into the four mounting posts.
The female extended header that comes with your HyperPixel 4.0 lifts it high enough to clear the USB and ethernet ports at the right-hand side of your Pi. Push the male end of the extended header into the female header on your HyperPixel firmly, until it's all the way in.
Now, push the extended header on your HyperPixel 4.0 onto your Pi's GPIO pins, making sure not to press on the centre of the HyperPixel's display but instead holding the edges of the display and PCB and pressing gently but firmly. Make sure that both headers are aligned properly; you can check this by looking at the alignment of the standoffs with the mounting holes on the Pi.
Flip your Pi over and secure the standoffs with the four metal screws, using a Phillips screwdriver. You can peel the film off the front of the display now, if you wish.
Using it with a Raspberry Pi Zero or Zero W
If you're using a Raspberry Pi Zero or Zero W, then you won't need to use the additional extended header, and just plug it straight onto the pins!
Setting up your Raspberry Pi
Download Raspberry Pi Imager and use it to flash the most recent 'recommended' version of Raspberry Pi OS onto your SD card. We sell a micro SD card that comes pre-loaded with Raspberry Pi OS, so if you're not sure what you're doing then you could grab one of them instead.
We'll be assuming you have a HDMI display, keyboard and mouse connected for the next part but, if you'd rather connect 'headlessly' you could use Raspberry Pi Imager to set up an SSH connection (or use Raspberry Pi Connect).
Pop the micro SD card with Raspberry Pi OS installed into the slot on the underside of your Pi and plug your power supply into the USB port; the Pi should start booting up.
Installing the HyperPixel 4.0 software
For the instructions below to work, you'll need to be using a version of Raspberry Pi OS that's dated after 04/04/2022. We'd recommend using the most recent version that's available (Bookworm or later).
We'll assume that you're starting from a fresh install of Raspberry Pi OS, and so have all the optional hardware interfaces disabled. Scroll down to the troubleshooting section for instructions how to disable them if you're unsure.
Editing config.txt
The Hyperpixel drivers are now built into Raspberry Pi OS, so all you need to do to get your screen working is add a line to /boot/firmware/config.txt.
In a terminal window ('Ctrl-Alt-T', or find it in the RPi OS menus), type the following and press enter to open the config file in a text editor:
sudo nano /boot/firmware/config.txt
Scroll down to the bottom of the file using the cursor keys, and add one of the following lines:
For rectangular Hyperpixel 4.0:
dtoverlay=vc4-kms-dpi-hyperpixel4
For Hyperpixel 4.0 Square (note that the new kernel drivers will only work with recent Hyperpixel Squares that have XP on the back):
dtoverlay=vc4-kms-dpi-hyperpixel4sq
For Hyperpixel 2.1 Round (note that touch is not supported with the new kernel driver):
dtoverlay=vc4-kms-dpi-hyperpixel2r
Once that's done, press 'Ctrl-X', then 'Y', then 'Enter' to save your changes.
You'll need to reboot your Pi for the new settings to take effect. You can do this from a terminal by typing 'sudo reboot'.
Once rebooted, your HyperPixel display should be displaying the Raspberry Pi OS desktop! Try touching the touchscreen, if you're using the Touch version of HyperPixel.
Rotation
If you want your screen to be a different way up, or landscape instead of portrait, the easiest way to rotate the display is by using the Screen Configuration utility that's built into Raspberry Pi OS. You can find this under the 'Preferences' menu.
The options to change the orientation are under the 'Screens' menu.
Our Pi 5 setup didn't require any additional config, but on some systems you may need to add additional lines to boot/firmware/config.txt to rotate the touch interface to match what's on the screen. Check out this Github issue for more information on the dtparam= options that are available.
If you're not bothered about using I2C, then you're done! If you want to learn more, then read on!
Using the alternate I2C interface (for advanced users)
HyperPixel uses literally all of the GPIO pins on the Raspberry Pi, including the standard I2C pins, but we've broken out some of the alternate I2C pins as well as 3V3 power and ground, so that you can use I2C devices at the same time as using your HyperPixel.
Recently manufactured Hyperpixels have a Qw/ST connector on board, so you can plug breakouts with Qw/ST connectors straight in with one of these handy cables.
If your Hyperpixel doesn't have a Qw/ST connector, you can use some jumper jerky to connect I2C devices, using the 5-pin female header on the underside of the board. If you're using our Pimoroni breakouts then you can solder a piece of right-angle male header on and plug them straight in.
You will first need to figure out the number of the interface that your Pi is using for Hyperpixel's I2C. You can list all the available interfaces with:
ls /dev/i2c*
You'll next need to find out which of these has your device connected to it. You can scan an interface like this, substituting your own number from the previous step if necessary:
i2cdetect -y 13
We can see that this is the correct bus for our Hyperpixel's I2C interface as our BME690 sensor is showing up with the I2C address 0x76 as expected.
Once you know the correct interface, you can symlink it to i2c-1 to fool any I2C devices into talking to the alternate one rather than the standard one. Open a terminal, and type the following, substituting '13' with your own number if it's different to ours:
sudo ln -s /dev/i2c-13 /dev/i2c-1
Now any software libraries that use I2C should talk to i2c-13 rather than to
i2c-1, meaning that you don't have to meddle with the sotware libraries
themselves.
If you want to undo this, you can simply delete the i2c-1 symlink file by typing in the terminal:
sudo rm /dev/i2c-1
Troubleshooting
Disabling I2C and SPI
Hyperpixel uses almost all the GPIO pins on your Pi to work, so if nothing's displaying on screen you'll want to make sure that any other interfaces that might try and use these pins are disabled.
Open a terminal prompt ('Ctrl-Alt-T', or find it in the Pi OS menus), and then type the following and press enter to open up the Raspberry Pi Configuration utility:
sudo raspi-config
Select 'Interfacing Options' and press enter.
Use the cursor keys to select SPI, then press enter.
Select 'No', and press enter:
The utility will confirm that the interface is disabled.
Repeat the steps above to disable I2C:
Exit the config utility when you're done, and reboot your Pi (sudo reboot from the terminal) for the changes to the interfaces to take effect.
Search above to find more great tutorials and guides.