[OS] Minimal Debian (u-boot, kernel, and Debian from scratch) [v0.2]

I created a clean Debian, and u-boot from scratch to be used in our device.

The menu is Retroarch. It boots directly to it in KMS mode (without X11). I have been working on an optimized version of retroarch with brightness control, more OSD options, power off, reboot on the menu, and other small features, but I decided to use the retroarch from the official repository. Maybe someone wants to use my build for other stuff, and it is very easy to uninstall retroarch now (apt uninstall retroarch). I’ll launch my retroarch in a dpkg file in the future to keep compatibility.

It can be written in a 1GB SD card, and the OS only uses 733MB of it. (Now you can use the 10 years old SD card you have in your drawer and still have space for a ton of roms!!!).

I documented as much as possible so someone else can recreate what I did. The skeleton (u-boot, kernel, partition procedure) can be the base for a Buildroot or another distribution.


  • Based on Debian Bullseye for the latest MESA driver with full lima support.
  • Clean OS with only Debian packages (no handmade compiled binaries) and small tweaks for hardware compatibility with gameshell.
  • No strange symbolic links nor duplicate files.
  • Max CPU frequency of 1.4GHz.
    • I don’t consider it an overclock. It is inside CPU specs, you can always use the governor settings to limit the frequency and increase battery life. The default governor is ondemand.
  • Standby mode (freeze) by pressing quickly the power key.
  • Power off by long-press (~2 seconds) the power key.
  • 733 MB of space occupied in the disk.
    • The system uses the minimum necessary to have a full Debian distribution with all the functionalities such as:
      • Package management (apt-get).
      • Wifi management with wpa-supplicant.
      • Bluetooth with bluez server.
      • DHCP server for USB ethernet functionality. I’m using network 192.168.11.x because some routers use the 192.168.10.x and using it will cause network problems.
      • SSH server.
      • Retroarch as a menu, and starting at boot. Takes around ~20 seconds from power on to get RetroArch running.
  • RAM usage of only 29MB, and 51MB with RetroArch running.
  • Cedrus support enabled in the kernel (The driver is compiled as a module, you need to enable it if you want to use).
    • This is for video encoding/decoding in hardware. The libva driver still not complete, but we should have it soon. This will be good if you want to record your game with retroarch and ffmpeg driver.
  • Charging LED is now in userspace (kernel 5.7).
    • I Patched the kernel. Now you have the charging LED (Orange LED) in the userspace at (/sys/class/leds/axp20x\:chgled/). You can control it manually (to use it for what you want like a normal led), or automatic (controlled by the charger).
  • Enabled status LED (green LED) to monitor (kernel 5.7):
    • Activity (CPU usage) [default mode], you can change it in the userspace.
    • Heartbeat. (I will use it later to signalize standby mode).
  • HDMI works and autodetects the screen resolution (up to 720p).
    • HDMI with hotplug detection.
    • The controller can read the screen information to use the best resolution available (up to 720p).
    • The HDMI is part of the kernel and can be manipulated with DRM.
  • U-boot configuration choose the dtb file for HDMI at boot time.
  • wifi driver is a kernel module now. We had issues with intermittent firmware loading. I hope it is fixed now.

Known Issues

  • HDMI sound doesn’t work.
    • The sound is routed to the GameShell speaker/headphone.


Kernel 5.7

Compiled binaries can be found inside bin folder of the repository.

Download the files:

and copy it to /BOOT

OS [v0.2]

Documentation and patches can be found on:

Edit 1: Organize functionalities, issues, and documentation in a list.
Edit 2: Updating with fixed issues.
Edit 3: New version v0.2 update.


that’s awesome, thanks a lot for your work !


Thanks, let’s see if people gets interested.

1 Like

Fixed LED issues :grinning:

I updated the main topic for simpler reading.

I will launch this update in the next release 0.2. I hope I can get HDMI working as well so the OS will be complete. I’m inclined to try to make HDMI work in real time (kernel) instead of the need to be recognized at boot (u-boot). I’ll see how difficult it is.

Regarding the LED’s, I used the patch from StefanMavrodiev. It adds a new driver in the Linux Kernel so we can have it in userspace and we change the behavior as we wish. I don’t know why this patch still not in the mainline. The driver is rich, and it is possible to change the operation modes, manual or automatic control. More information can be seen at


  • Charging LED is now in userspace (next release 0.2).
    • I Patched the kernel. Now you have the charging LED (Orange LED) in the userspace at (/sys/class/leds/axp20x\:chgled/). You can control it manually (to use it for what you want like a normal led), or automatic (controlled by the charger).

I enabled some configurations in the kernel, so the status LED can monitor the CPU.

  • Enabled status LED (green LED) to monitor (next release 0.2):
    • Activity (CPU usage) [default mode], you can change it in the userspace.
    • Heartbeat. (I will use it later to signalize standby mode).

it cannot be more clean, i hope it will be adopted as default base in future :slight_smile:

hopping also external additions will be released as deb packages

your research make some advance, all community will give benefits from them :sunflower:


I LOVE the idea of having a clean Debian based image for the clockwork pi. The official image is a bit of a mess.

Do you happen have a script / manifest / playbook for building the image?

If not do you have step by step instructions? I’d be up for trying to create an automated process for building images.

(This is assuming you don’t already have one, sorry, just excited and doing some speaking without thinking)


thanks for your great work!!!
I’m very interested in sleep function. How can I adapt it to default OS of Gameshell?

1 Like

Yes, I documented everything in the github page:

Thanks for your interest. I think it should be straightforward to make a bot to compile it with the commands I listed. The only thing missing is to create a virtual sd card for the process.

If you can do it, please, send me a patch :slight_smile:

I’m busy working on the HDMI problem.


What enables this function (sleep and power key) is a patch in the kernel. You can use the patch I used in my github page. All the procedure to make it can be found there, go to the section Kernel in the

Keep in mind that “sleep” is in reality “freezing”. All the information can be found here:

1 Like

I’m improving a lot in the HDMI.

I found a kernel driver that fits the it66121 (our RGB -> HDMI converter). I created another patch with the driver, updated the device tree and now it is working :slight_smile:

In the official image this driver is inside u-boot. We never got the source code for u-boot, which defeats the “An Open Source Portable Game Console” :weary:

The good things are:

  • HDMI with hotplug detection.
  • The controller can read the screen information to use the best resolution available (up to 720p, but I know a way to get full HD :sweat_smile:).
  • The HDMI is part of the kernel and can be manipulated with DRM.

The bad:

  • Sound over HDMI doesn’t work yet.

Working on:

  • I don’t know if I can do it, but I want to have an automatic change when we are using LCD or HDMI. If I see that it is extremely difficult I will focus in getting the sound and find a way to patch u-boot to look for a specific *.dtb when it detects the HDMI cable (like we have in the official image).

This is huge news. This opens a lot of possibilities and hope for the project! I you have a specific thread for the “asking for the missing source part” tell us so we can go and voice our concern there too!

Whenever I get the time I’ll go through your instructions to make sure they are reproducible and that we can improve the documentation.

Thanks a lot :raised_hands: for this work ! I might be able to recommend this device after all !

Thanks for your support.

The missing part is the u-boot patch. I think the way I’m getting it to work is better (kernel drivers), but I still need to understand how to get the audio working. If we have the code I could work in another thing… maybe the deep sleep.


tks! I’ve decide to apply your kernel patch to default OS and it works, boot screen is mixed but i’m ok with it :slight_smile:
Freezing works, I tried with RetroArch and sometime it made GS launcher to reload after resuming. But I can take the risk :smiley:

Wow, by far the fastest-booting image from what I’ve been able to test!


To get the clockworkpi logo back, you can use this patch:

The GS launcher (for what I remember) works inside a while loop and reload after you close the application, in your case Retroarch. So your retroarch is being closed for one motive…

I tried here with my image, and I can keep retroarch running with a game loaded in memory. After wakeup I can still play my game from the same point I left.


Thanks for trying :grinning:

I updated the repository.

In the new patch for kernel 5.7 I enabled support for the new HDMI driver, but without sound over HDMI. The sound is routed to the gameshell speaker for now.

In the new BOOT.scr I enabled an option for u-boot choose the correct *.dtb file when the HDMI cable is connected.

Instead of having a new release, I decided to provide the compiled kernel, and dtb files so you can just copy the files to your /BOOT directory and get the new drivers working, keeping your system without changes.

Honestly speaking the 0.1 release is almost a definitive OS. You can update everything from apt and keep up to date. We need to work only with the kernel, maybe I could create a deb file so you could update the kernel easily.



Thank you a lot for you hard work!

1 Like

I followed the instructions on your git repo with a new 32GB card and it worked wonderfully!

May be worth adding some notes about which build dependencies are required for people following along there. I had most already, but needed multistrap, qemu-user-static, etc.

Great work. Thanks!


Thanks for trying!

The reason I didn’t add the build dependencies is because I don’t really know :joy:

multistrap, and qemu is for the script, but there are many others that you probably already have