Having a nice display and a Pi is all well and good. But I’m not here to sit there on Raspberry Pi OS. Naturally, the display works without issue on the latest Pi OS. A little change to boot/firmware/config.txt, enable the driver, and you’re done. The display works.
But I’m not here for Raspbian. I am here to learn, and I have more to learn from Kali.
First, some ingredients:
This is the GitHub page for the base driver for HyperPixel4. Let’s call it the ‘manual driver’.
https://github.com/pimoroni/hyperpixel4
This is the GitHub page for a fork of the driver that supposedly takes the pain out of setting it up. It was written for Kali 2024, which, as I would come to find out, is a different use case than Kali 2025.3. Let’s call this one ‘the easy driver’.
https://github.com/cons0le7/hyperpixel4-kali
Should be simple. Just use the ‘easy driver’, right? Well… no. It’s not that simple. Because at some point, Raspberry Pi added vc4-KMS support for HyperPixel4 natively, which leads us to driver number 3. Let’s call this one ‘the kernel driver’.
https://github.com/raspberrypi/firmware/blob/master/boot/overlays/vc4-kms-dpi-hyperpixel4.dtbo
This one ships with Kali, and Raspberry Pi. It is the one that worked for Raspbian.
Before I could get far, I had to fix something. Until I could get the display working, the only way to run commands on Kali is through SSH or a display server. Opting for the simpler option, I chose SSH. But it was excruciatingly slow. I would type, and then occasionally wait several seconds before it was registered.
I edited the sshd_config by typing sudo nano /etc/ssh/sshd_config, then added a comment before the X11 forwarding line:
X11Forwarding yes
to:
#X11Forwarding yes
This dramatically sped up my SSH session and enabled me to debug properly.
Attempt 1. Try the kernel driver.
I followed these steps:
-> Edit /boot/firmware/config.txt
dtoverlay=vc4-kms-v3d
…
dtoverlay=vc4-kms-dpi-hyperpixel4
Reboot.
It works in Raspbian, so surely it will work here, right? No. Using this combination led to an interesting state:
>The display manager, LightDM, was running, and by all accounts should be working.
>Xorg appeared to be running, too. Logs show nothing useful.
>Yet this yields nothing: dtoverlay -l
>Checked /sys/class/drm/ folders. All the right stuff. So what gives?
Upon further investigation… and by ‘further investigation’, I mean several hours spanning multiple days of dmesg this, cat that, reflashing, rebooting, I couldn’t get it to run.
Attempt 2. Try easy driver.
Cons0le7 has put together a wonderful little python utility, shown above, designed to take the headache out of installing. It is definitely designed to be the easy driver.
The process is simple, and described better on the page. But to give it briefly:
->Clone the github link.
->cd into the folder.
->run ‘python3 easy.py‘.
This is where it gets a little odd. The script downloads the ‘manual driver’ from Pimoroni’s github, makes sure Python3 and the GPIO libraries are properly installed, and does some housekeeping. Great. But upon entering the installer, I am met with a few options:
Pi 4+
[0] Rectangular
[1] Weirdly Square
Pi 3B
[3] Rectangular
[4] Weirdly Square
But the device I’m running is a Pi Zero 2 W. So what do I pick?
I picked the closest option — 0, hoping the Pi 4 is close enough.
No dice. The terminal shows, no display manager, no desktop.
I tried every iteration and every option again and again, and the result was always the same. No GUI. I even tried re-flashing.
Eventually, I realized a possible cause — since the fork was created, /boot/config.txt was changed to /boot/firmware/config.txt. I looked into the install script for both Cons0le7 and Pimoroni, and all assume the folder must end in /boot/.
I tried rewriting the scripts to reflect the new folder to no avail. The result was clear — I wasn’t going to get either of these working on Kali 2025.3.
Attempt 3. Try the framebuffer driver.
I decided to try the classic fallback of just running the frame buffer directly. No hardware acceleration, but at least I’d know the screen works. After a little bit of configuration, I rebooted to find a screen. Great! Job’s done, right?
Well, no. Not unless I want to try to use a portrait screen run across the length of my forearm. I needed landscape, and there’s no good way to rotate a framebuffer (at least that I am aware of). But it did pass a crucial test — the display would work with Kali, just not in the way I had it set up.
I won’t go into the setup for this, mostly because I don’t recall exactly what it was.
Attempt 4. The easy driver, revisited
I do not know why the KMS driver will not work in Kali 2025. I have not figured it out. But I had a sinking suspicion that it had to do with the major jump in kernel that moved /boot/config.txt to /boot/firmware/config.txt. So I decided to try something new — I acquired the same exact version of Kali 2024 used in Cons0le7’s driver. Crucially, this particular version retains /boot/overlays/ and /boot/config.txt.
I booted up Kali 2024. I had to do some tricks to get sudo apt update to work, but once I did, I was able to run the ‘easy driver’ once again. I once again picked [0] for Raspberry Pi 4 (despite being on a Raspberry Pi Zero 2 W), and let it install. I rebooted, got ready to SSH back in and debug once again, but I stopped.
In front of me was a beautiful sight. A kali logo. But I wasn’t done yet, because the kali logo didn’t go away. I was not logged in, and I had no way to log in!
Next up, I configured LightDM via sudo nano /etc/lightdm/lightdm.conf, then I added my user as follows:
[Seat:*]
autologin-user=username
autologin-session=xfce
When I rebooted, I was met with a desktop, once again in portrait mode. I needed to rotate the display. Thanks to Cons0le7, this is easy — running their rotate.py script successfully rotated the display. I was almost done, except for one problem.
The touchscreen was off by a lot. Pressing on the left would give it a correct position, but on the right, it would go way offscreen.
It took me longer than I am willing to admit to realize that is because I didn’t disable composite, and so I was running two displays. I simply went to the now-accessible display settings, disabled the composite screen, and there it was.
A lot of pain, a lot of learning, and a whole new appreciation for the people who contribute to Linux later, I was met with a beautiful sight.
It finally works. It is not flawless — I will one day figure out how to get this working on the latest Kali. But for now, I have a more important problem to solve, one that is equal parts engineering and equal parts fashion:
I need a battery system I can look good in.
That will be part 3.