# A General Guide to Porting Distros to the uConsole and Devterm

**URL:** <https://forum.clockworkpi.com/t/a-general-guide-to-porting-distros-to-the-uconsole-and-devterm/20156>\
**Category:** Tutorials\
**Tags:** tinkering, os, help, devterm, uconsole\
**Created:** [October 21, 2025, 4:58am UTC](https://forum.clockworkpi.com/t/a-general-guide-to-porting-distros-to-the-uconsole-and-devterm/20156 "2025-10-21T04:58:49Z")\
**Posts on this page:** 2\
**Page:** 1

<div class="post-metadata">

**Author:** ![crossplatformdev](https://yyz1.discourse-cdn.com/flex029/user_avatar/forum.clockworkpi.com/crossplatformdev/32/14698_2.png) [@crossplatformdev](https://forum.clockworkpi.com/u/crossplatformdev)\
**Post date:** [October 21, 2025, 4:58am UTC](https://forum.clockworkpi.com/t/a-general-guide-to-porting-distros-to-the-uconsole-and-devterm/20156/1 "2025-10-21T04:58:50Z")

</div>

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 `ssh` or by connecting an external keyboard and monitor).

```auto
# 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.12.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.**

> **[uConsole/Code/patch at master · clockworkpi/uConsole](https://github.com/clockworkpi/uConsole/tree/master/Code/patch)**
>
> This code repository offers downloads for the latest images of various uConsole models, along with kernel patches, firmware for the keyboard and 4G expansion module, hardware schematics, assembly i...

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](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`:

```auto
[all]
dtparam=audio=on
auto_initramfs=1
max_framebuffers=2
disable_overscan=1
arm_boost=1
ignore_lcd=1
dtoverlay=audremap,pins_12_13
dtoverlay=dwc2,dr_mode=host
dtparam=ant2
dtparam=spi=on          

[pi3]
#dtoverlay=clockworkpi-uconsole-cm3
dtoverlay=clockworkpi-devterm-cm3
dtoverlay=vc4-kms-v3d,cma-384
enable_uart=1
[pi4]
#dtoverlay=clockworkpi-uconsole
dtoverlay=clockworkpi-devterm
dtoverlay=vc4-kms-v3d-pi4,cma-384
dtparam=pciex1=off
enable_uart=1
[pi5]
#dtoverlay=clockworkpi-uconsole-cm5
dtoverlay=clockworkpi-devterm-cm5
dtoverlay=vc4-kms-v3d-pi5,cma-384
dtparam=pciex1=off

```

Have a great day!

**Do you want also some suggestions about what to do now? I’ve got you covered!**

> [@\[Jammy, Bookworm, Trixie\] for uConsole and DevTerm CM3, CM4 & CM5 (flashable .xz images built by CI/CD)](https://forum.clockworkpi.com/t/ubuntu-22-04-4-for-uconsole-cm4-flashable-xz-image/14240/43):
>
> I would like to share a little guide with tips, with little tweaks that can be done after flashing the image and configuring it during the first boot slight_smile Installing a different Desktop Environment.: Open a terminal, type sudo apt install -y tasksel, then run sudo tasksel, a ncurses menu will open for you to select ‘tasks’, which are basically groups of packages and settings for doing determined tasks. You can enable sshd there too, or even install a LAMP server. I personally use gn…

**Do you wish for a simpler way to cook your own distro? Check this!**

> [@Recipe for Debian 13 Trixie Linux 6.12.32 CM3, CM4 & CM5](https://forum.clockworkpi.com/t/recipe-for-debian-13-trixie-linux-6-12-32-cm4/20175):
>
> Hi everyone, I’m sharing a guide on how to create a custom Debian 13 “Trixie” image for the uConsole, using only the ClockworkPi APT repository. Let’s assume the following: You’ve installed a server Debian-based distro (Bookworm or Trixie) onto an SD card using Raspberry Pi Imager. In Raspberry Pi Imager’s advanced settings, you set a hostname, created 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…

---

<div class="post-metadata">

**Author:** ![Toml\_12953](https://yyz1.discourse-cdn.com/flex029/user_avatar/forum.clockworkpi.com/toml_12953/32/11925_2.png) [@Toml\_12953](https://forum.clockworkpi.com/u/Toml_12953)\
**Post date:** [October 21, 2025, 2:38pm UTC](https://forum.clockworkpi.com/t/a-general-guide-to-porting-distros-to-the-uconsole-and-devterm/20156/2 "2025-10-21T14:38:17Z")

</div>

Thanks for that! Messages like that are exactly what I need. YouTube videos tend to include a lot of extra commentary and background stuff that’s irrelevant to getting the software up and running. Your instructions are clear and to the point.