HackberryPi CM5 — Setup & Troubleshooting Guide

Raspberry Pi OS Bookworm on the ZitaoTech HackberryPi CM5: from a freshly imaged eMMC to a clean-booting, fully functional device.

A field guide by Kevin JH / Bio-Architectonic — written after setting up a CM5 unit (8GB RAM / 32GB eMMC, Raspberry Pi OS 64-bit Bookworm Desktop) as a portable field debugger for a research project. Everything below was hit, diagnosed, and resolved on real hardware. Shared so the next person gets there faster.

The end state this guide gets you to: internal display + keyboard working, SSH from a laptop, offline LLM via Ollama. Kernel string visible in the background terminal: 6.12.75+rpt-rpi-2712.

TL;DR — the three things most likely to ruin your day:

1. Kernel 6.18 breaks the internal display. Pin the kernel to 6.12.75+rpt-rpi-2712 and hold it.
2. I2C/SPI must stay disabled permanently — the DPI panel owns those GPIOs for the lifetime of every boot.
3. If the keyboard or trackpad isn't responding, check the left-side toggle switch first. It routes the keyboard between CM5-internal and external USB-C. It is not a driver problem.

---

Contents

1. Issue 1 — Kernel 6.18 display regression
2. Issue 2 — GPIO conflicts: DPI vs I2C/SPI
3. Issue 3 — Overlay file locations in the official repo
4. Issue 4 — initramfs mismatch after kernel pinning
5. Issue 5 — The keyboard toggle switch
6. Final working config.txt
7. Result / verification checklist

---

Issue 1 — Kernel 6.18 breaks the HyperPixel4 Square display

Symptom: internal display does not initialize at all on Raspberry Pi OS Bookworm once the system is on kernel 6.18.29+rpt-rpi-2712.

Cause: a known upstream regression affecting the HyperPixel4 Square DPI panel — see raspberrypi/linux#6878 (regression introduced from 6.12.30+).

Fix — pin the kernel to a known-good 6.12 build:

# 1. The 6.12 kernel + initramfs are still present under /boot/ after upgrade.
#    Swap them into the firmware partition:
sudo cp /boot/kernel_2712.img      /boot/firmware/kernel_2712.img      # 6.12.75+rpt-rpi-2712
sudo cp /boot/initramfs_2712       /boot/firmware/initramfs_2712

# 2. Hold the 6.18 packages so apt upgrades don't reintroduce the regression:
sudo apt-mark hold linux-image-rpi-2712 linux-headers-rpi-2712

Adjust package names to whatever apt list --installed | grep linux-image shows on your system — the point is to hold every package that would pull a 6.18 kernel back in.

After pinning, confirm with uname -r → 6.12.75+rpt-rpi-2712.

---

Issue 2 — GPIO conflicts: DPI display vs I2C/SPI (permanent)

Symptom: display fails to initialize, with kernel log lines like:

pin gpioN already requested by ... i2c
drm-rp1-dpi: Error applying setting, reverse things back

Cause: the DPI panel drives GPIO 2/3 and 7–11. With dtparam=i2c_arm=on or dtparam=spi=on enabled, I2C/SPI claims those pins first and the display loses.

Fix: keep both permanently disabled in /boot/firmware/config.txt:

#dtparam=i2c_arm=on
#dtparam=spi=on

The trap: this is not a first-boot-only setting. Re-enabling dtparam=i2c_arm=on after the display is working will silently break it on the next reboot — the panel holds those pins for the lifetime of every boot. If you need external I2C sensors, route them through software I2C on different GPIOs instead.

---

Issue 3 — Overlay (.dtbo) file location

The README under Operating System/RaspberryPi_OS/ in the official repo says to download the dtbo files "in this page," but the actual files live one level up, in Operating System/:

• hyperpixel4.dtbo
• vc4-kms-dpi-hyperpixel4sq.dtbo
• hackberrypi.dtbo

Quickest way to find them:

git clone https://github.com/ZitaoTech/HackberryPiCM5
find HackberryPiCM5 -name "*.dtbo"

Copy them to /boot/firmware/overlays/.

---

Issue 4 — initramfs_2712 auto-matching after kernel downgrade

Symptom: after manually pinning the kernel (Issue 1), every boot throws "no matching initramfs" — auto_initramfs=1 keeps trying to match the (now-removed) 6.18 initramfs.

Fix: declare the initramfs explicitly in /boot/firmware/config.txt:

initramfs initramfs_2712 followkernel

Edge case, but anyone doing manual kernel pinning will hit it.

---

Issue 5 — The keyboard physical toggle switch

Symptom: keyboard and trackpad appear completely dead. You will be tempted to debug I2C drivers — especially after reading Issue 2.

Reality: the keyboard is USB-HID, running QMK on its own dedicated MCU. It needs no drivers and is unrelated to the GPIO conflicts above. There is a physical toggle switch on the left side of the device that routes the keyboard between:

• CM5-internal — normal operation
• External USB-C — for editing the keymap with VIAL from another computer

If input is dead, flip the switch. That's it. (Hours of my life, summarized in one sentence. It's genuinely clever engineering once you know it's there — it just deserves to be the first line of any troubleshooting checklist.)

---

Final working config.txt

Tested on: HackberryPi CM5 · CM5 8GB/32GB eMMC · Raspberry Pi OS 64-bit Bookworm Desktop · kernel pinned at 6.12.75+rpt-rpi-2712.

[all]
dtoverlay=vc4-kms-v3d
dtoverlay=hackberrypi
initramfs initramfs_2712 followkernel
#display_auto_detect=1
#dtparam=i2c_arm=on
#dtparam=spi=on

Plus, outside config.txt:

• Kernel manually copied to /boot/firmware/kernel_2712.img (6.12.75)
• 6.18 kernel packages held via apt-mark hold
• Left toggle switch in CM5-internal (USB-HID) position

---

Result

With the above applied, the device reaches:

• ✅ Clean boot sequence (no initramfs errors)
• ✅ Internal 720×720 display working
• ✅ Keyboard + trackpad working (USB-HID, no drivers)
• ✅ SSH from a laptop, headless operation
• ✅ Local LLM via Ollama for offline use

---

Notes

• These notes are specific to the CM5 variant on Bookworm; other OS images in the official repo may differ.
• Found an error, or did a newer kernel fix the regression? Issues and PRs welcome.

---

Maintained by Kevin JH — Bio-Architectonic. The HackberryPi CM5 serves as the field debugger for an ongoing research/wearable project.