Hi everyone,
I’d like to share a guide on how to port a distro to the uConsole, since there’s very little documentation available.
In essence, the process comes down to installing a kernel that already includes the drivers for the uConsole—or patching an existing kernel source to add driver support—then compiling, packaging, and installing it on a working Raspberry Pi image.
For this guide, I’ll be using the kernel from @ak-rex along with the Ubuntu 24.04 image for the Raspberry Pi 4.
Let’s assume the following:
-
You’ve installed a distro onto an SD card using Raspberry Pi Imager.
-
In Raspberry Pi Imager’s advanced settings, you configured a hostname, set up a user and password, and enabled SSH.
-
You’ve booted the uConsole and have a way to run the following commands on it (either by logging in via
sshor by connecting an external keyboard and monitor).
# Ctrl W + Ctrl R, Search 'deb', replace by 'deb-src', Ctrl-O save as /etc/apt/sources.list.d/ubuntu-src.sources, press Y
sudo nano /etc/apt/sources.list.d/ubuntu.sources
# Create workdir
mkdir uconsole
mkdir uconsole/linux
cd uconsole/linux
# Install dependencies
sudo apt update
sudo apt build-dep linux linux-image-raspi
sudo apt install libncurses-dev gawk flex bison openssl libssl-dev dkms libelf-dev libudev-dev libpci-dev libiberty-dev autoconf llvm
sudo apt install bc bison flex libssl-dev make
sudo apt install git fakeroot
# Download original and updated raspberrypi kernel source
# Adjust branch appropiatedly for the kernel version of your distro.
git clone --depth=1 --branch rpi-6.14.y https://github.com/raspberrypi/linux.git
cd linux
# Download the diff file containing the patch that enables support for uConsole.
wget https://github.com/raspberrypi/linux/compare/rpi-6.12.y...ak-rex:ClockworkPi-linux:rpi-6.12.y.diff
# If there's rejections, you'll have to manually check what's left out and manually place it correctly in the destination file, or do a 3-way merge and cherrypick the conflicts.
patch -p1 < rpi-6.12.y...ak-rex:ClockworkPi-linux:rpi-6.12.y.diff
# Prepare to compile.
KERNEL=kernel8
make bcm2711_defconfig
# Optional: Edit kernel config
# make menuconfig
# Compile with this exact command, or flash-kernel will fail.
make -j6 deb-pkg LOCALVERSION="-raspi"
# Binaries will be in ../ after this
# Install with dpkg
sudo dpkg -i ../linux-*.deb
# If the kernel was successfully installed, reboot. Otherwise, execute this commands:
# make -j6 Image.gz modules dtbs
# sudo make -j6 modules_install
# sudo cp /boot/firmware/$KERNEL.img /boot/firmware/$KERNEL-backup.img
# sudo cp arch/arm64/boot/Image.gz /boot/firmware/$KERNEL.img
# sudo cp arch/arm64/boot/dts/broadcom/*.dtb /boot/firmware/
# sudo cp arch/arm64/boot/dts/overlays/*.dtb* /boot/firmware/overlays/
# sudo cp arch/arm64/boot/dts/overlays/README /boot/firmware/overlays/
# This won't generate the .deb package but are the GP instructions from raspberrypi.com.
The drivers included in ak-rex’s kernel diff originally come from the ClockworkPi repository.
After running all the uncommented lines above and rebooting, if everything went correctly, the screen, keyboard, trackball, battery, and LEDs should be working. However, you’ll still need a small piece of software to manage the uConsole GPIO pins for the fan, audio, and 4G extension. You can take a look at this script I wrote for my distro:
https://github.com/crossplatformdev/uConsole-Image-Builder/blob/main/make_gpio_package.sh
And that’s pretty much all you need. However, be aware that you’ll have to repeat this process whenever you update the kernel, and unattended system upgrades can brick your distro if your custom-compiled kernel gets replaced by an unpatched one. If that happens you’ll need to reinstall a patched kernel (ssh, or chroot into the sdcard from a host computer) and make sure it boots.
To prevent this, you can either hardcode the kernel version you want to boot in /boot/firmware/config.txt, or use apt-mark hold on the generated .deb packages.
I’ve just tested this process, all that was missing was to add the proper settings in config.txt:
[all]
kernel=vmlinuz
cmdline=cmdline.txt
initramfs initrd.img followkernel
camera_auto_detect=1
display_auto_detect=1
# Config settings specific to arm64
arm_64bit=1
disable_overscan=1
dtparam=audio=on
max_framebuffers=2
ignore_lcd=1
dtoverlay=dwc2,dr_mode=host
dtoverlay=vc4-kms-v3d-pi4,cma-384
#dtoverlay=clockworkpi-devterm
dtoverlay=clockworkpi-uconsole
dtoverlay=audremap,pins_12_13
dtparam=spi=on
#dtparam=ant2
##Comment out the device not needed in [all]
dtparam=pciex1_gen=3
gpu_mem=256
Have a great day!
Do you want also some suggestions about what to do now? I’ve got you covered!
Do you wish for a simpler way to cook your own distro? Check this!