Skip to content

Instantly share code, notes, and snippets.

@assada

assada/uconsole.md

Last active January 7, 2026 00:25
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save assada/71a1aa6d086e59dc9876b780bcc5d6c9 to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save assada/71a1aa6d086e59dc9876b780bcc5d6c9 to your computer and use it in GitHub Desktop.
Download ZIP
Raw
uconsole.md

uConsole - The Definitive Guide

📑 Table of Contents

Introduction & Release Overview

Image Description

The ClockworkPi-Bookworm-6.12.y image is a community-maintained operating system for the uConsole and DevTerm, developed to replace the stock distribution. While the stock distro utilizes kernel 5.10, which is "almost 5 years old and does not receive updates," these images are current with kernel 6.12 [User: Rex, Post #217].

This release is built using Pi-Gen and is noted as the "last release of Bookworm" by the maintainer [User: Rex, Post #1].

Supported Hardware

The image is designed to work with the following configurations:

  • uConsole: CM3, CM4, and CM5.
  • DevTerm: CM4 and CM5. [User: Rex, Post #1]

Kernel & Architecture

  • Kernel Version: 6.12.y.
  • Source Code: The rpi-6.12.y branch is available on GitHub, with ClockworkPi drivers pre-marked to compile in bcm2711_defconfig or bcm2712_defconfig [User: Rex, Post #1].
  • PCIe & Ethernet: These features have been updated and enabled to prepare the system for new adapter boards [User: Rex, Post #1].
  • Charge Light: Functionality for the charge light was restored in Kernel 6.12.28 [User: Rex, Post #474].

Key Features

The image includes the following pre-configured features [User: Rex, Post #1]:

  • Editions: Desktop and Lite images available.
  • Visuals: Dark mode enabled for all screens (first boot, login, desktop) and a collection of ClockworkPi wallpapers.
  • Power: Sane charging defaults applied.
  • Updates: Kernel updates provided through the maintainer's APT repo.
  • WiFi: External WiFi antenna already set in config.txt.
  • Development: linux-headers included with the kernel.
  • Storage: Auto-expanding file system (on first boot, the system will expand the filesystem and then reboot).
  • Configuration: Updated driver overlays for easier config.txt management.

4G/LTE Management

The image includes specific commands to manage the optional 4G card [User: Rex, Post #1]:

  • To activate: uconsole-4g enable
  • To deactivate: uconsole-4g disable

(See Connectivity: WiFi, 4G, & Ethernet for detailed configuration).

Installation & First Boot

SD Card Selection

For the uConsole, particularly with the Raspberry Pi Compute Module 5 (CM5), the choice of microSD card significantly affects boot success rates. The CM5 has known timing sensitivities when booting off SD cards in the uConsole carrier board prior to specific EEPROM configurations.

  • Recommended: SanDisk Extreme 512GB. Users consistently report this card "Seems to be far better behaved" compared to others and is the preferred choice for stability [User: thoughtfix, Post #16].
  • Problematic: Samsung Evo Select (specifically 512GB). Users reported the device "Never even lit up the panel backlight after 10 minutes and several retries" [User: thoughtfix, Post #16].
  • Initial Provisioning Strategy: If you encounter boot failures with large capacity cards (128GB+), use a smaller, older SD card (e.g., 32GB) for the initial setup. Smaller cards "are more likely to work and you only have to use that SD to make the change" to the EEPROM. Once the EEPROM is updated, you can swap back to your larger, preferred SD card [User: Rex, Post #313, #618].

Flashing the Image

The official community image is built using Pi-Gen and supports both Desktop and Lite versions. It is compatible with DevTerm CM4/5 and uConsole CM3/4/5 [User: Rex, Post #1].

  1. Download: Obtain the latest image (e.g., Bookworm 6.12.y or later) from the provided mirrors (Mega, Google Drive, or Drime) [User: Rex, Post #1].
  2. Flash: Use Raspberry Pi Imager to flash the .img.xz file to your SD card.

⚠️ CRITICAL WARNING: NO CUSTOM SETTINGS Do not apply any "OS Customization" settings (User/Pass, WiFi, Hostname) within the Raspberry Pi Imager.

  • "Raspberry Pi Imager will cause image not to boot if you apply custom settings." [User: Rex, Post #1]
  • "if flashing with rpi imager don’t apply any custom settings... a normal first boot will... boot into the first boot wizard." [User: Rex, Post #822]

The First Boot Sequence

The first boot process is automated and involves heavy filesystem operations. It is normal for the device to appear inactive for a period.

  1. Insert SD Card and power on the device.
  2. Wait: The screen may remain black initially. "The screen won’t turn on till the kernel loads the driver for it." [User: Rex, Post #148].
  3. Automated Steps: The system will boot, automatically expand the filesystem to fill the SD card, and then reboot itself [User: Rex, Post #1].
  4. Completion: After the automatic reboot, the device should launch the first-boot wizard (OOBE) where you can set your language, time zone, and user credentials.

⚠️ Note: "This is normal and you don’t want to interrupt this process." Do not force power off during the filesystem resize [User: Rex, Post #148].

Post-Boot Configuration: EEPROM Update (CRITICAL)

This step is mandatory for CM5 and CM5 Lite users. To ensure reliable booting from SD cards, enable NVMe support, and fix power management issues, you must update the bootloader configuration. If you have a CM5 Lite, you must have firmware dated after 2025-01-06 [User: Rex, Post #1].

Once you have reached a terminal (via SSH or the device screen), follow these steps exactly:

1. Check Firmware Version Verify your bootloader version.

vcgencmd version

If the date is older than January 2025, update it immediately:

sudo rpi-eeprom-update -a
sudo reboot

2. Edit the EEPROM Configuration Open the bootloader configuration editor:

sudo rpi-eeprom-config -e

3. Apply the Configuration Block Replace the existing configuration (backup the old text if desired) with the following block. This configuration optimizes boot order (SD -> NVMe -> USB -> Network), fixes SD card timing quirks, and manages power states [User: Rex, Post #1]:

[all]
BOOT_UART=1

# Switch off PMIC outputs on HALT
POWER_OFF_ON_HALT=1

# Default BOOT_ORDER for provisioning
# SD -> NVMe -> USB -> Network
BOOT_ORDER=0xf461

# Try boot on SDCard repeatedly
SD_BOOT_MAX_RETRIES=2

# Slow down SDCard SDR Mode on bootloader
SD_QUIRKS=1

4. Save and Exit

  • Press Ctrl+S to save.
  • Press Ctrl+X to exit.
  • Reboot the device (sudo reboot) to apply changes.

Troubleshooting Initial Boot

If the device fails to initialize the display or hangs on the green status light, try the following methods in order.

1. The "Hot-Swap" Method (SD Card Detection)

If the CM5 is not detecting the SD card to apply EEPROM modifications, the device may hang before video output starts.

  • Action: "Boot up the uConsole, wait about 30 seconds, then remove and reinsert the SD card while the device is still on."
  • Result: This forces the hardware to re-poll the storage bus. Users have reported success with this method even when multiple SD cards failed initially [User: Quixote, Post #524].

2. The CM5 Lite "IO Board" Method

Primary solution for CM5 Lite users. The CM5 Lite (no eMMC) is notoriously difficult to boot inside the uConsole until the EEPROM is patched. If you cannot boot to a terminal on the uConsole:

  1. Remove the CM5 Lite module from the uConsole.
  2. Install the CM5 Lite onto a standard Raspberry Pi CM4/CM5 IO Board.
  3. Boot the IO Board using the SD card.
  4. Perform the EEPROM Configuration steps listed above (specifically adding SD_QUIRKS=1).
  5. Reinstall the module into the uConsole.
  • "You can boot the CM5 in a IO board to make the changes... The EEPROM changes will stay with the module so you can switch back." [User: Rex, Post #313, #772].

3. External Display / OOBE Navigation

If the internal LCD remains black but the device seems active (green light flashing), connect an external HDMI monitor.

  • Issue: The internal screen might be blank, but the external screen shows a wallpaper without the setup wizard.
  • Fix: Connect a USB keyboard. Hold down SHIFT during boot. This can force the OOBE (Out of Box Experience) screen to appear on the internal display (potentially sideways), allowing you to complete the setup [User: thoughtfix, Post #15].

4. Recovery Binary (Alternative)

If you cannot boot Linux to run the commands, you can attempt to flash the EEPROM using a recovery.bin file.

  1. Download a pre-configured eeprom.bin or rename a known working bootloader image to recovery.bin.
  2. Copy it to the root of a FAT32 formatted SD card (the boot partition).
  3. Insert into the uConsole and power on. The CM5 should flash the EEPROM automatically [User: paragonnov, Post #45].

CM5 Specific Configuration & EEPROM

The Raspberry Pi Compute Module 5 (CM5), particularly the "Lite" variant (without onboard eMMC), requires specific EEPROM configurations to function correctly with the uConsole carrier board. Without these changes, the device is "picky about what SD card it boots" and may fail to initialize high-capacity cards [User: Rex, Source 1, Post #8].

3.1 Critical EEPROM Update for CM5 Lite

If you have a CM5 Lite and are experiencing issues with the SD card booting, you must update the EEPROM. The CM5 Lite requires updated firmware released after 2025-01-06 [User: Rex, Source 1, Post #1].

Configuration Steps: Please refer to Installation & First Boot: Post-Boot Configuration for the exact commands and the required configuration block (SD_QUIRKS=1, POWER_OFF_ON_HALT=1, etc.).

⚠️ Warning: Do not use the Raspberry Pi Imager's "Custom Settings" (gear icon) when flashing the OS image. This "will cause image not to boot if you apply custom settings" [User: Rex, Source 1, Post #1].

3.2 Recovery Methods for Non-Booting Units

If your CM5 Lite refuses to boot the SD card to allow you to run the commands above, use one of the following methods to apply the fix.

Method A: The "Small Card" Technique

"Smaller [SD cards] are more likely to work" to get the system booted the first time. A 32GB card often works where larger cards fail. Once booted, apply the EEPROM changes; the "EEPROM changes will stay with the module so you can switch back to a bigger SD" [User: Rex, Source 1, Post #313].

Method B: The "Hot Swap" Trick

If the CM5 is not detecting the SD card:

  1. "Boot up the uConsole" (without the SD card, or with it inserted but failing).
  2. "Wait about 30 seconds."
  3. "Remove and reinsert the SD card while the device is still on." This forces the bootloader to re-read the card [User: Quixote, Source 1, Post #524].

Method C: Automated Recovery Binary

For users who cannot boot into Linux, a pre-configured recovery binary can flash the EEPROM automatically.

  1. Download the EEPROM file (e.g., pieeprom.bin from a release after 2025-01-06).
  2. Rename the file to recovery.bin.
  3. Copy it into the root directory of the SD card (the FAT32 partition that contains kernel_2712.img).
  4. Boot the uConsole. The CM5 will flash the EEPROM with the recovery file.
  5. If it stays in the bootloader, "try eject and insert your sdcard when cm5 is running" [User: paragonnov, Source 1, Post #45].

Method D: IO Board

If you have access to a Compute Module 4/5 IO Board, you can "boot the CM5 in a IO board to make the changes" before installing it into the uConsole [User: Rex, Source 1, Post #313].

3.3 Kernel Page Size Management (16k vs 4k)

By default, the CM5 uses a 16k page size kernel (kernel_2712.img). While performant, this breaks compatibility with certain software, such as Box86/Box64 and Wine [User: Rex, Source 1, Post #31].

Switching to 4k Page Size

To run software requiring 4k pages (like Wine), you must force the system to use the kernel8.img (the 2711 kernel compatible with CM4/5).

  1. Edit the configuration file:

    sudo nano /boot/firmware/config.txt

    [User: Rex, Source 1, Post #199]

  2. Add the following line to the [all] section:

    kernel=kernel8.img

    [User: Rex, Source 1, Post #199]

  3. Reboot the system.

ℹ️ Note: "2711 and 2712 are kernels, 2711 is for the CM4&5 and 2712 is just for the CM5 but with a 16k page size." [User: Rex, Source 1, Post #31].

3.4 Fixing Corrupted EEPROM via USB Boot

If you encounter "Failed to open partition" errors or suspect a corrupted EEPROM (e.g., after a failed update), you can recover the device using the rpiboot utility.

Prerequisites:

  • A separate host computer running Linux (e.g., a PC or another Raspberry Pi). You cannot run these commands on the uConsole itself while it is in a non-booting state.
  • A USB-A to USB-C data cable connecting the host computer to the uConsole.

Step 1: Prepare the Host Environment

On your separate host computer, clone the usbboot repository and build the tool.

  1. Clone the repository:

    git clone --recurse-submodules --shallow-submodules --depth=1 https://github.com/raspberrypi/usbboot

    [User: Chad_Vavra, Source 1, Post #854]

  2. Build the rpiboot tool:

    cd usbboot
make INSTALL_PREFIX=/usr/local

    [User: Chad_Vavra, Source 1, Post #854]

Step 2: Update the EEPROM Binary

It is critical to update the binary before flashing. Note: The directory differs depending on whether you are recovering a CM4 or CM5. For the CM5, you must use the recovery5 directory.

  1. Navigate to the correct recovery directory (use recovery5 for CM5):

    cd recovery5

    [User: Chad_Vavra, Source 1, Post #856]

  2. Run the update script to fetch the latest bootloader images:

    ./update-pieeprom.sh

    [User: Chad_Vavra, Source 1, Post #856]

Step 3: Flash the Device

Ensure your uConsole is connected via USB to the host computer and powered on (in USB slave mode).

  1. Return to the root usbboot directory:

    cd ..

    [User: Chad_Vavra, Source 1, Post #856]

  2. Run rpiboot pointing to the recovery5 directory. This forces the tool to serve the CM5-specific binaries rather than the default CM4 versions:

    sudo rpiboot -d recovery5

    [User: Chad_Vavra, Source 1, Post #856]

Once the process completes, the EEPROM should be restored, allowing you to boot normally from an SD card.

CM5 Thermal Management & Power Stability

The Raspberry Pi Compute Module 5 (CM5) offers significant performance gains over the CM4, but these improvements come with increased thermal and power demands. While the CM5 idles at lower power, it draws almost twice the power at full load compared to its predecessor [User: Greg_E, Source Post 210].

This increased power draw presents two distinct challenges:

  1. Thermal Throttling: Without adequate cooling, the device may throttle or shut down under sustained load.
  2. Voltage Sag: The boost converter on the carrier board may struggle to maintain 5V as battery voltage drops (typically below 50%), leading to instability, shutdowns, or audio artifacts [User: Rex, Source Post 209].

Temperature & Throttling Monitoring

To accurately monitor clock speeds, voltages, and thermal throttling status, use the following script provided by the maintainer. This script is essential for verifying if your cooling solution is adequate or if the system is undervolting.

Monitoring Script: Create a script (e.g., monitor_temp.sh) with the following content:

#!/bin/bash

vcgencmd get_config int | egrep "(arm|core|gpu|sdram)_freq|over_volt"
for src in arm core h264 isp v3d; do echo -e "$src:\t$(vcgencmd measure_clock $src)"; done
for id in core sdram_c sdram_i sdram_p ; do echo -e "$id:\t$(vcgencmd measure_volts $id)"; done
vcgencmd measure_temp
throttled="$(vcgencmd get_throttled)"
echo -e "$throttled"
if [[ $throttled != "throttled=0x0" ]]; then
    echo "WARNING:  You are being throttled.  This is likely because you are undervoltage.  Please connect your PI to a better power supply!"
fi
sleep 10

[User: Rex, Source Post 433]

Software Solutions: Frequency Management

Adjusting the CPU and GPU frequencies is the most effective way to manage heat and battery life without physical modifications. Underclocking can also prevent the system from shutting down when battery levels are low (below 50%) by reducing the peak power draw on the boost converter.

Moderate Underclock (Efficiency)

To run efficiently for longer periods and improve stability with KDE, reduce the processor and GPU frequencies in /boot/firmware/config.txt. Users report this allows the device to run down to 0% battery without premature shutdowns [User: Kirou, Source Post 119, 214].

gpu_mem=256
gpu_freq=500
arm_freq=1800

Aggressive Underclock (Maximum Battery/Cooling)

For maximum power saving or if you are experiencing frequent thermal shutdowns:

arm_freq=1000
arm_freq_min=500
gpu_freq=800
gpu_freq_min=500

[User: Rex, Source Post 433]

Overclocking (High Performance)

Users have successfully overclocked the CM5, but this significantly increases heat output. The device will get "spicy" and requires additional cooling solutions for loads lasting more than 10-15 minutes [User: Rex, Source Post 138].

Experimental Overclock Settings:

over_voltage_delta=50000
arm_freq=2800
gpu_freq=1000

[User: Rex, Source Post 426]

⚠️ Warning: Overclocking increases the risk of instability and thermal throttling. Ensure you have a robust cooling solution (see Hardware Modifications below) before applying these settings.

Hardware Modifications

Due to the CM5's high heat output, the stock thermal configuration may be insufficient for heavy loads. Community members have verified the following hardware improvements.

External M.2 Heatsink

A popular non-destructive modification involves mounting a standard M.2 SSD heatsink to the back of the unit. This increases the surface area for passive cooling.

  • User rhithyn reported that with an M.2 heatsink mounted to the back, temperatures peaked at 70°C under load, improving passive cooling significantly [Source Post 136].
  • User Rex noted that an M.2 heatsink allowed for short-burst overclocking (2800MHz CPU / 1000MHz GPU) [Source Post 138].

Custom Battery Solutions (Advanced)

The thermal and stability issues of the CM5 are closely linked to power delivery. The standard 1S battery configuration can struggle to deliver the required wattage once voltage drops below 3.8V, causing freezes.

  • User avs.andrew replaced the stock battery module with a custom 2S (Series) configuration using two protected 21700 batteries and a separate balanced charging controller. This setup provides a constant voltage via a step-down converter, eliminating low-voltage freezes and allowing the CM5 to run at high load (85% CPU) for approximately 3 hours [Source Post 170, 196]. (See Hardware Extensions & Modifications for more details).

Thermal Pad Adjustments

The thickness of the thermal pad affects the fitment of the back shell and heat transfer.

  • User thoughtfix noted that the device is sensitive to pressure and thermal pad thickness, particularly when using adapter boards (like the Waveshare adapter). Ensuring the pad is not too thick is crucial to avoid pressure on the board which can cause display failures [Source Post 15].
  • User BronzeBeard reported that for emulation tasks (e.g., running Windows 95 via 86Box), the stock thermal pad is sufficient to keep temps around 55°C at stock clocks [Source Post 81].

Addressing Power-Induced Audio Noise

A side effect of the CM5's high power draw is "coil whine" or static coming from the speakers when the battery drops below 50% [User: Frost26, Source Post 531]. This is a hardware issue related to voltage drops affecting the audio path.

Workarounds:

  1. Hardware: Plugging a device into the 3.5mm headphone jack stops the noise from the speakers [User: Rex, Source Post 533].
  2. Software: You can disable the specific GPIO pin causing the interference using the following command: 
    sudo pinctrl set 11 op dl
    To restore it, use sudo pinctrl set 11 op dh [User: YoelFievelBenAvram, Source Post 545].

Input Devices: Stock vs. QMK Firmware

The uConsole features a 74-key ortholinear keyboard and a 19mm optical trackball. While the hardware interface is fixed, the behavior of these inputs is governed by the firmware running on the keyboard's dedicated microcontroller (ATMega32U4). This firmware operates independently of the Operating System, meaning changes to the OS do not automatically update input behavior.

Keyboard Layout Configuration (GB vs US)

A common issue for new users involves incorrect key mappings due to the Raspberry Pi OS defaulting to the Great Britain (GB) keyboard layout.

Symptoms of Incorrect Layout:

  • The \| key produces # and ~.
  • Pressing Shift + 3 produces a GBP sign (£) instead of #.
  • Pressing Shift + @ produces """.

Resolution: To correct this, you must reconfigure the locale settings within the OS to use the US layout.

  1. Open the Raspberry Pi configuration tool: 
    sudo raspi-config
  2. Navigate to 6 Localization Options.
  3. Select L3 Keyboard.
  4. Ensure the model is set to Generic 105-key PC.
  5. Select English (US) as the layout.

Once applied, the keys should map correctly. If issues persist, ensure you have not selected a specific uConsole keyboard layout that may not exist, and stick to the generic 105-key US standard.

[Source: Eduardolicious, Post 26; Rex, Post 27; Rex, Post 73; REDROBRC, Post 72]

Firmware Comparison: Stock vs. QMK

The uConsole ships with "Stock" firmware, but the community (and ClockworkPi) has made available a ported version of QMK firmware. The QMK firmware is highly recommended by the community for its expanded feature set, particularly regarding scrolling and gaming controls.

Feature Stock Firmware QMK Firmware
Scrolling Direction Vertical only (Up/Down) Multi-directional (Up/Down/Left/Right)
Scroll Activation Fn + Trackball Select + Trackball
Gamepad Mode Standard Arrow Keys Toggleable D-Pad (Groups arrows with game buttons)
Trackball Feel Standard Reported as easier to use, though may have slight latency

[Source: Rex, Post 156; Kirou, Post 154; NAA, Post 160; white-round-square, Post 155]

Key Differences:

  • Scrolling: On the official stock firmware, users are limited to vertical scrolling (mono-scrolling). The QMK firmware enables "poly-scrolling," allowing for left and right navigation, which is essential for certain applications. [Source: Rex, Post 156; white-round-square, Post 158]
  • Gamepad Mode: QMK introduces a "Gamepad Mode." This allows the arrow keys to be switched into a D-pad configuration that belongs to the same input group as the ABXY game buttons. This is a significant quality-of-life improvement for emulators that require a unified controller input. [Source: Rex, Post 159; NAA, Post 160]
  • Zooming: Functionality such as using the "mouse wheel" (trackball scroll) to zoom in and out of applications is dependent on the firmware capabilities. [Source: mattconn24, Post 193; Rex, Post 194]

Flashing the Firmware

Because the keyboard controller is separate from the main system, updating the OS (e.g., apt upgrade) will not update the keyboard firmware. You must manually flash the microcontroller.

Requirements:

  • Firmware File: Community members recommend using QMK firmware versions from late 2024 (specifically referencing the September 22, 2024 build). [Source: Rex, Post 75]
  • Flashing Tools: You must use the specific uConsole keyboard flashing tools provided in the ClockworkPi GitHub repository. [Source: white-round-square, Post 157]
  • Execution Environment: The flashing tools should be run directly on the uConsole itself, not from an external PC. [Source: white-round-square, Post 157]

General Process:

  1. Download the flashing tool and the desired firmware binary (Stock or QMK) from the official ClockworkPi GitHub or community links.
  2. Execute the flashing script on the uConsole.
  3. If successful, the input behavior will change immediately (e.g., scrolling combinations will shift from Fn to Select).

Note on Reverting: If you wish to revert from QMK back to Stock firmware, you must follow specific restoration instructions provided by community members (such as user @olly) on the forums. [Source: Rex, Post 629]

Known Issues

  • USB-A Disconnection (Bookworm): Some users running Raspberry Pi OS Bookworm have reported that plugging in a USB-A device causes the keyboard and mouse to disconnect completely after flashing QMK. This issue was not present prior to the firmware update. [Source: sergpc, Post 628]
  • Trackball Latency: While the QMK firmware improves usability and scrolling, some users report the trackball has "a little latency" compared to the stock version, though it is generally considered a worthy trade-off for the added features. [Source: Kirou, Post 154]

Display & Graphics Subsystem

This release introduces significant changes to the display stack, moving to a unified driver architecture and the standard V3D graphics stack.

The Unified Panel Driver (cwu50)

The 6.12.y kernel introduces a new panel driver designed to support multiple hardware iterations.

"A new driver was added that supports both (old & new) panels, and in my testing the same driver worked with both the CM4&5 with the old (current) panel. So I’ve switched out the old panel drivers that needed one for the CM4 and one for the CM5, for the new driver that works with both." [User: Rex, Post #382]

However, the driver has known sensitivity regarding initialization timing.

"The issue with the panel driver is mostly with probe ordering and timing – the driver gets probed and initialized before the supply voltage regulators are, so the first initialization sequence does exactly nothing." [User: PeterCxy, Post #382]

If the driver fails to initialize, dmesg logs may show:

panel-cwu50 fe700000.dsi.0: supply vci not found, using dummy regulator
panel-cwu50 fe700000.dsi.0: supply iovcc not found, using dummy regulator
panel-cwu50 fe700000.dsi.0: failed to send initialize sequence (-110)

[User: zedstarr, Post #143]

Troubleshooting Initialization Failures

The display driver issues often manifest as a black screen (with backlight on) during boot.

Cold Boot vs. Reboot

The panel has a higher failure rate when powering on from a completely off state (Cold Boot) compared to a software restart.

"If you can SSH in reboot the screen has a better success rate on reboots then cold boots." [User: Rex, Post #14]

"But if I do a Reboot it works perfect but if I Shutdown then turn it back on again it goes blank screen and after a few try’s it boots ok" [User: Sherlock_XGP, Post #105]

The "Blind Reboot" Technique

If the screen is black but the backlight is on, the system is likely running. You can attempt a blind reboot to re-initialize the panel:

"If you get a black screen just wait a bit then hit the power button once hit the down arrow key and hit enter (blind rebooting)" [User: Rex, Post #31]

Alternatively:

"If the panel doesn’t display an image then just double tap the power button to shutdown." [User: Rex, Post #77]

Kernel Reinstall Fix

If boot failures persist, reinstalling the kernel package can resolve initialization issues by updating the initramfs and modules.

sudo apt reinstall clockworkpi-kernel

[User: Rex, Post #109]

"I can confirm cold boots are working now as well as screen blanking." [User: n1f7, Post #117]

Screen Rotation

The native orientation of the panel requires software rotation.

The raindrop Utility

For immediate rotation within the standard Desktop Environment (DE):

"Are you using the standard DE? if so just run raindrop and rotate the panel." [User: Rex, Post #60]

Configuration Files

For persistent rotation, configuration depends on the compositor or display manager used.

Kanshi (Wayland):

profile {
output DSI-1 enable mode [email protected] position 0,0 transform 270
}

[User: Hatchback4, Post #330]

Sway:

output DSI-1 mode 480x1280@60Hz transform 90

[User: stibbons, Post #332]

GPU Acceleration: V3D vs. llvmpipe

The system should utilize the Broadcom V3D hardware renderer. However, configuration conflicts can cause it to fall back to llvmpipe (software rendering), resulting in poor performance.

Verifying the Renderer

You can check the active renderer using glmark2 or system info tools.

Correct (Hardware Acceleration):

GL_VENDOR:      Broadcom
GL_RENDERER:    V3D 7.1.10.2
GL_VERSION:     OpenGL ES 3.1 Mesa 24.2.8-1~bpo12+rpt1

[User: Rex, Post #169]

Incorrect (Software Rendering):

GL_VENDOR:      Mesa
GL_RENDERER:    llvmpipe (LLVM 15.0.6, 128 bits)
GL_VERSION:     OpenGL ES 3.2 Mesa 24.2.8-1~bpo12+rpt1

[User: Rex, Post #169]

Performance Impact

"they got 202 [glmark2 score], on my underclocked uconsole cm5 i just got 151." [User: Rex, Post #163]

With V3D working correctly:

"Just finished glmark2-wayland : 1135... At full speed, score are 1820 for both tests." [User: Kirou, Post #168]

Resolving Mesa Conflicts

The fallback to llvmpipe is often caused by a specific Mesa update.

"So I figured out whats wrong, it was a mesa update... I used the script here someone made to fix the problem... downgraded mesa and now glmark2-es2-wayland works as intended." [User: Rex, Post #195]

In some cases, simply ensuring all packages are upgraded resolves missing library links:

"another update (sudo apt update && sudo apt upgrade) fixes the issue (mesa-libgallium installed, libegl-mesa0 libgbm1 libglapi-mesa libglx-mesa0 updated)" [User: teo, Post #88]

Power Management & Battery

Calibrating the AXP228 Battery Indicator

The uConsole uses an AXP228 Power Management Unit (PMU). On a fresh installation or after battery replacement, the battery percentage indicator may be inaccurate or stuck. The controller requires a manual calibration cycle to learn the capacity of the installed cells.

Calibration Procedure:

  1. Charge to 100%: Ensure the device is fully charged.
  2. Activate Calibration Mode: Run the following command in the terminal: 
    echo 1 | sudo tee /sys/class/power_supply/axp20x-battery/calibrate
    [User: Rex, Source 1: Post #21]
  3. Verify Status: You can check if calibration is active by reading the value. A return value of 48 indicates it is calibrating. [User: Rex, Source 1: Post #140]
  4. Discharge: Drain the device completely until it powers off.
  5. Recharge: Charge the device back to 100% while it is powered on. [User: Rex, Source 1: Post #21, #142]

⚠️ Note: If the battery level drops below 50-40% before calibration is complete, the panel may cut off due to voltage drops on the CM5. [User: Rex, Source 1: Post #19]

CM5 Audio Noise & Low Battery Instability

Users with the Compute Module 5 (CM5) may experience specific hardware-related power issues when the battery charge drops.

Symptoms:

  • "Scraping/scratching sounds out the speakers."
  • "Pulsing when the processing gets higher or when there are more screen redraws."
  • "Crackling noise... very apparent during boot and shutdown." [User: NumbaWon, Source 1: Post #205; User: giftsonjebin, Source 1: Post #243]

Cause: This is a hardware power issue with the main board and the CM5. The CM5 draws significantly more power than the CM4 (almost twice the power at full load). The uConsole uses a boost-type power supply to step up the battery voltage (nominal 3.7V) to 5V. As the battery voltage sags (around 50%), the boost converter struggles to maintain stability, causing ripple noise in the audio lines. [User: Rex, Source 1: Post #209; User: Greg_E, Source 1: Post #210, #339]

Workarounds:

  1. 3.5mm Dummy Plug: The whine comes out of the speakers, not the Compute Module itself. Plugging headphones or a dummy plug into the 3.5mm jack will stop the noise from the speakers. [User: white-round-square, Source 1: Post #544]
  2. Underclocking: Lowering the CPU and GPU frequencies can reduce current draw, allowing the device to run down to zero battery without crashing. (See CM5 Thermal Management & Power Stability).
    • Example: CPU at 1800 MHz and GPU at 600 MHz. [User: Kirou, Source 1: Post #214]
  3. Screen Brightness: Paradoxically, some users report changing brightness to max can alter the load characteristics. [User: white-round-square, Source 1: Post #206]

The "Green Light of Death" (GLOD)

A common failure state involves the device failing to shut down completely, leaving the green status LED dimly lit.

Symptoms:

  • Screen is black.
  • Green LED stays "dimly lit" or "lightly lit."
  • Power button does not shut down the device. [User: Astearon, Source 1: Post #48; User: ToXicHardWare, Source 1: Post #267]

Immediate Recovery: If the device enters this state, the power button logic is unresponsive. You must physically cut power:

  1. Open the battery compartment.
  2. Take out the batteries.
  3. Wait a few seconds and replace them. [User: REDROBRC, Source 1: Post #99; User: doctaphil, Source 1: Post #13]

Prevention (EEPROM Config): To prevent the PMIC outputs from staying active during a halt, ensure the POWER_OFF_ON_HALT=1 line is present in your EEPROM configuration. (See Installation & First Boot: Post-Boot Configuration for editing instructions). [User: Rex, Source 1: Post #1]

Battery Hardware Requirements

The uConsole, particularly with the CM5, is sensitive to battery quality. Generic batteries can cause voltage drops under load, leading to shutdowns even when capacity remains.

  • Recommendation: Use high-quality 18650 cells.
  • Known Issues: "Generic batteries are definitely the problem... cheap batteries can have some bad voltage drop when under load." [User: Rex, Source 1: Post #301]
  • Voltage Drop: Under load, if battery voltage drops below 3.8V, the console may hard freeze. [User: avs.andrew, Source 1: Post #170]

Connectivity: WiFi, 4G, & Ethernet

This section details the configuration of wireless and wired networking on the uConsole running the ClockworkPi-Bookworm-6.12.y image. It covers the management of the Compute Module's antenna selection, activation of the optional 4G/LTE module, and the configuration of Ethernet adapter boards.

WiFi Configuration and Antenna Management

The uConsole relies on the wireless capabilities of the Raspberry Pi Compute Module (CM4 or CM5).

⚠️ Warning: The CM5 is not wired to access the main board's WiFi. You will either have to get a WiFi-enabled CM5 or use a USB adapter [User: Rex, Source 1, Post 38].

Antenna Selection (Internal vs. External)

The ClockworkPi-Bookworm-6.12.y image has the external WiFi antenna already set in config.txt [User: Rex, Source 1, Post 1].

To verify or change this setting, edit /boot/firmware/config.txt:

dtparam=ant2

[Source: github.com/assada/uconsole.md]

  • dtparam=ant2: Selects the external antenna connector (U.FL) on the Compute Module.
  • Commented out (# dtparam=ant2): Selects the internal PCB antenna on the Compute Module.

Signal Interference Troubleshooting

If the uConsole cannot connect to a home AP but connects to a mobile hotspot, or indicates low signal strength while near the router, it is likely an antenna issue [User: white-round-square, Source 1, Post 513].

The stock antenna attached to the chassis can cause interference due to the metallic body.

  1. Insulation: Put something in between the stock antenna and the uConsole, such as "a few mm of something like electrical tape to move it away of metallic body" [User: white-round-square, Source 1, Post 516].
  2. Orientation: Try to point the uConsole directly to the router [User: white-round-square, Source 1, Post 513].

4G/LTE Cellular Connectivity

The 4G extension is a USB module with a script to turn it on separately via GPIO [User: snipeytje, Source 1, Post 703]. The Bookworm 6.12.y image includes utilities to manage this card.

Enabling and Disabling the Modem

To activate the 4G card:

uconsole-4g enable

[User: Rex, Source 1, Post 1]

To deactivate the 4G card:

uconsole-4g disable

[User: Rex, Source 1, Post 1]

Troubleshooting 4G Scripts

If the standard command does not work or the script is missing after an update:

  1. Manual Execution: If using a specific CM5 script manually, ensure it is executable:

    sudo ./uconsole-4g-cm5.txt enable

    [User: Rex, Source 1, Post 486]

  2. Script Location: If the script is not found in the path, it may need to be moved to /usr/local/bin/ and chmodded to executable (chmod +x). You can create a launcher script in /usr/bin/ that calls the script in /usr/local/bin/ [User: duckyvirus, Source 1, Post 492].

Ethernet & PCIe Adapter Boards

The 6.12.45 image has updated and enabled PCIe and Ethernet to get ready for new adapter boards [User: Rex, Source 1, Post 1].

Enabling PCIe for Ethernet

For expansion boards utilizing the PCIe interface (such as the HackerGadgets RJ45 Ethernet and USB 3.0 expansion board), the PCIe interface must be enabled in the configuration.

Edit /boot/firmware/config.txt to include:

dtparam=pciex1=on

[Source: github.com/assada/uconsole.md]

Hardware Options

  • HackerGadgets Upgrade Kit: Includes an RJ45 Gigabit Ethernet port directly connected to the CM4/5 [Source 3, HackerGadgets Forum Post].
  • uEther Expansion: Uses a LAN9500 Hi-Speed USB 2.0 to 10/100 Ethernet Controller [Source 3, uConsole World].

Storage Expansion: NVMe & PCIe

The uConsole supports NVMe storage expansion through specific adapter boards. This functionality is primarily targeted at the Compute Module 5 (CM5), though support extends to the CM4. The operating system image has been prepared to support these hardware additions out of the box.

PCIe Support in OS

In the 6.12.y image (specifically 6.12.45 and later), the system has "Updated and enabled PCIE and Ethernet to get it ready for the new adapter boards that are coming out" [User: Rex, Source 1, Post #1].

Users do not need to manually edit config.txt to enable PCIe, as this configuration is pre-applied in the image.

Adapter Board Support

Community-developed adapter boards are required to utilize NVMe drives. According to forum maintainers, "NVME capable adapter boards from @vileer & @lululvlv" have been developed [User: Rex, Source 1, Post #762].

Features associated with these DIY extension boards include:

  • NVMe Support: M.2 extension capabilities.
  • Connectivity: "4g（CAT1）+typec" and "Double typec ports extend card" [User: Rex, Source 1, Post #760].
  • Power: References to "new Battery" implementations [User: Rex, Source 1, Post #760].

EEPROM Configuration for CM5 Lite

For the CM5 Lite, specific EEPROM configurations are required to establish the correct boot priority between SD cards and NVMe drives. This is particularly important because "the CM5 is picky about what SD card it boots without changing the eeprom" [User: Rex, Source 1, Post #8].

⚠️ Critical Warning: These EEPROM instructions are for the CM5 Lite only. "There’s nothing you need to do to the eeprom with the CM4" [User: Rex, Source 1, Post #853].

Updating the EEPROM

To configure the system for NVMe boot priority, you must edit the EEPROM configuration.

  1. Ensure your CM5 Lite has updated firmware (released after 2025-01-06). Check using vcgencmd version and update via sudo rpi-eeprom-update if necessary [User: Rex, Source 1, Post #1].
  2. Edit the configuration: 
    sudo rpi-eeprom-config -e
  3. Replace the existing configuration with the required block.

Configuration Block: Please refer to Installation & First Boot: Post-Boot Configuration for the exact configuration block (BOOT_ORDER=0xf461, SD_QUIRKS=1, etc.).

Boot Order Explanation

The setting BOOT_ORDER=0xf461 establishes the following priority sequence:

  1. SD Card (1)
  2. NVMe (6)
  3. USB (4)
  4. Network (f)

[User: Rex, Source 1, Post #1]

This ensures the device attempts to boot from the SD card first. If the SD card is absent or fails, it will attempt to boot from the NVMe drive.

Hardware Constraints: eMMC vs. SD

Users selecting a Compute Module must be aware of hardware conflicts regarding bus usage.

  • Bus Conflict: On the CM5, "the emmc and sd are on the same bus that’s why if you have emmc the sd won’t work" [User: Rex, Source 1, Post #644].
  • Implication: If you possess the eMMC variant of the CM5, you cannot simultaneously use the SD card slot for storage or booting in the standard configuration. The "disable eMMC boot" jumper on IO boards is used only to flash the eMMC or SD, but does not resolve the runtime bus conflict [User: Rex, Source 1, Post #644].

Troubleshooting Boot Issues

Symptoms

If the EEPROM is not configured correctly, or if the SD card is not recognized, the system may fail to boot.

  • Error Message: "failed to boot device nvme" (seen when the system skips the SD card and tries NVMe) [User: Batman, Source 1, Post #613].
  • Visual Indicator: The power button may show a green light, but the screen remains blank [User: pagamble, Source 1, Post #630].

Solutions

  1. Use a Smaller SD Card: "Using a smaller SD card usually works better to get it to boot the first time. After you edit the eeprom you can use whatever size SD you want" [User: Rex, Source 1, Post #614]. Users have reported success using 32GB cards to perform the initial boot and EEPROM update, after which larger cards (e.g., 512GB) function correctly [User: Batman, Source 1, Post #618].

  2. Avoid Custom Imager Settings: When flashing the OS, do not use custom settings in the Raspberry Pi Imager. "Raspberry Pi Imager will cause image not to boot if you apply custom settings" [User: Rex, Source 1, Post #1].

  3. Use an IO Board for Recovery: If the uConsole refuses to boot any SD card, you may need to use a CM5 IO board.

    • Flash a standard Raspberry Pi OS image to an SD card.
    • Boot the CM5 in the IO board.
    • Perform the EEPROM edit (sudo rpi-eeprom-config -e) on the IO board.
    • Transfer the CM5 back to the uConsole.
    • User Experience: "I had to go down the IO board route in order to edit the EEPROM but it worked... Flashed 6.12.45 to a big sd card, and reassembled the uconsole and a few long seconds after pressing power everything booted!" [User: backer954, Source 1, Post #818].

  4. Corrupted EEPROM Recovery: If the EEPROM becomes corrupted (e.g., by applying CM5 settings to a CM4), you may need to use rpiboot with the recovery directory to restore it [User: Chad_Vavra, Source 1, Post #854]. (See CM5 Specific Configuration: Fixing Corrupted EEPROM).

Hardware Extensions & Modifications

10.1 HackerGadgets All-In-One (AIO) Expansion Board

The HackerGadgets AIO board is a popular expansion that integrates RTL-SDR, LoRa, GPS, RTC, and a USB Hub. It is confirmed to work with both CM4 and CM5 core modules.

Automated Installation

For users running the Bookworm 6.12.y image, a pre-configured package is available to streamline the setup process. This package installs necessary dependencies and u-dev rules.

To install the package:

sudo apt update && sudo apt --install-recommends install hackergadgets-uconsole-aio-board

Note: As of the latest update, the Real Time Clock (RTC) is not automatically configured by this package and may require manual setup. [User: Rex, Post #609, #550]

10.2 Internal USB & Storage Modifications

The uConsole chassis has sufficient internal clearance to accommodate specific USB dongles and storage modifications, allowing for "stealth" integrations of hardware.

Internal TV Tuners / SDR Users have successfully fitted USB Digital TV Tuners (specifically RTL2832U based dongles) inside the case.

  • Fitment: While some dongles fit directly, users may need to remove the plastic casing from the USB device depending on its girth.
  • Modification: To ensure a better fit, it may be necessary to modify the internal plastic battery holder. One user reported cutting a chunk of the PCB/battery holder to accommodate an SDR card. [User: Rex, Post #398, #400, #404; User: jutleys, Post #399]

Internal Mass Storage It is possible to connect an SSD to the internal ports to act as a mass storage device. This setup works with both CM4 and CM5.

  • Usage: The SSD can be used as a boot drive or as a secondary storage drive while booting from the SD card. [User: white-round-square, Post #507]

10.3 Battery & Power Modifications

The CM5 module has a significantly higher power draw than the CM4, particularly under load (high CPU/GPU usage). This can lead to audio crackling, system instability, or shutdowns when battery voltage drops (often around 50-70%). To mitigate this, the community has developed advanced battery modifications.

2S (Series) Battery Pack Mod To prevent voltage sag and hard freezes, users have replaced the stock parallel (1S) battery setup with a custom series (2S) configuration.

  • Configuration: Two protected 21700 batteries connected in series.
  • Hardware Required:
    • Separate balanced charging controller with USB-C.
    • Step-down converter outputting a constant 4.2V to the mainboard.
  • Benefits: Allows the CM5 to run stable from 100% capacity down to 0% (8.4V down to 6V at the battery), eliminating low-voltage freezes.
  • Trade-offs:
    • Loss of Native Charging: The stock USB-C port on the uConsole will no longer charge the batteries; the custom added USB-C port must be used.
    • Battery Indicator: The OS battery percentage indicator will become inaccurate or non-functional (e.g., sticking at 5%). [User: avs.andrew, Post #170, #196, #387]

⚠️ Warning: Modifying Li-Ion battery configurations carries significant risk of fire or device damage. This modification requires advanced soldering skills and knowledge of battery safety.

10.4 3D Printed Modifications

Antenna Mounts The metal chassis of the uConsole can interfere with WiFi and RF signals.

  • Interference Fix: Users report that the stock antenna attached directly to the metal chassis results in reduced signal strength.
  • Solution: Printing a spacer or mount (e.g., "uConsole micro antenna 0.2 mount by m3x") to lift the antenna a few millimeters off the metal body significantly improves reception. [User: white-round-square, Post #516; User: duckyvirus, Post #493]

Chassis Customization Community members have designed various printable parts to enhance functionality:

  • Side Panels: Custom right-side panels to add external connectors for RTL-SDR and GPS antennas.
  • Screen Protection: Hinged screen covers and rubberized screen protectors. [User: duckyvirus, Post #493]

10.5 4G/LTE Modem

The 4G extension module is supported in the Bookworm image, though CM5 users may need to apply specific patches due to pinout differences.

Standard Operation To manage the modem power state:

uconsole-4g enable
uconsole-4g disable

[User: Rex, Post #1]

(See Connectivity: WiFi, 4G, & Ethernet for more details).

CM5 Compatibility & Troubleshooting If the 4G script is missing or fails on a CM5 device after an update:

  1. Locate the CM5-specific patch on the ClockworkPi GitHub (PR #33).
  2. Extract the script and place it in /usr/local/bin/.
  3. Ensure the script is executable: chmod +x /usr/local/bin/<script_name>.
  4. Create a launcher script in /usr/bin/ if necessary to map the command. [User: Rex, Post #482; User: duckyvirus, Post #490, #492]

Maintenance & Updates

System Update Strategy

The ClockworkPi-Bookworm-6.12.y image is configured to receive kernel updates through a custom APT repository. You can update the system normally to receive these updates.

Standard Update Command:

sudo apt update && sudo apt upgrade

[User: white-round-square, Post #310]

Note: "You can update normally and you’ll receive my kernel updates just like a normal RPi OS install." [User: Rex, Post #311]

Kernel Management

The distribution uses specific packages for the kernel and firmware: clockworkpi-kernel and clockworkpi-cm-firmware.

Installing/Updating the Kernel: If you are not getting kernel updates or need to overwrite an older kernel, use the following commands:

sudo apt update
sudo apt install clockworkpi-kernel clockworkpi-cm-firmware

[User: Rex, Post #54]

Reinstalling the Kernel: If you encounter issues or need to force a refresh of the kernel and initramfs, you can reinstall the package:

sudo apt reinstall clockworkpi-kernel

[User: Rex, Post #109, #146]

Note: "if you do sudo apt reinstall clockworkpi-kernel it will update the initramfs for both kernels". [User: Rex, Post #131]

Troubleshooting Initramfs Errors

A known issue exists where updates to initramfs-tools may replace configuration changes required for the custom kernel to build an initramfs. This can result in a "post-install script subprocess returned error status 1" during updates.

The Fix: To resolve this, you must modify the initramfs.conf file to ensure modules are loaded correctly.

  1. Run the following command to patch the configuration:

    sudo sed -i '/^MODULES=dep/c\MODULES=most' "/etc/initramfs-tools/initramfs.conf"

    [User: Rex, Post #443]

  2. Finish the upgrade or reinstall the kernel:

    sudo apt reinstall clockworkpi-kernel

    [User: Rex, Post #443]

Manual Initramfs Update: You can also trigger the initramfs update manually for all kernels:

update-initramfs -c -k all

[User: Rex, Post #131]

Handling Held Packages

Users may encounter errors where packages are "held" and cannot be upgraded. This typically occurs because the package "relies on the updated package that’s held" [User: Rex, Post #212].

In the context of this distribution, resolving kernel dependencies often fixes these holds.

sudo apt update
sudo apt reinstall clockworkpi-kernel

[User: Rex, Post #286]

Troubleshooting Guide

12.1 The "Blind Reboot" Trick

If the uConsole powers on and the backlight illuminates (a grey/black glow) but no image appears, the system is likely running but the display driver failed to initialize. This is a known issue with the CM5 drivers where the panel has a better success rate on reboots than cold boots.

Procedure:

  1. Wait a moment to ensure the system has reached the login screen/desktop.
  2. Press the Power Button once.
  3. Press the Down Arrow key once.
  4. Press Enter.

"If you get a black screen just wait a bit then hit the power button once hit the down arrow key and hit enter (blind rebooting)" [User: Rex, Post #31]

(See Display & Graphics Subsystem for technical details).

Alternative (Blind Shutdown): If the blind reboot fails or you wish to power off safely:

  • Double-tap the power button to trigger a shutdown.

    "If the panel doesn’t display an image then just double tap the power button to shutdown." [User: Rex, Post #77] "This method has worked for me 100%." [User: REDROBRC, Post #99]

12.2 "Green Light of Death" (Dim Green LED)

Symptoms:

  • The device freezes or is hard shutdown (holding the power button).
  • The green power LED remains dimly lit instead of turning off.
  • The power button becomes unresponsive; the device will not reboot or turn off.
  • "I also noticed some whines/electrical noise and the screen being slightly lit during the dim light phase." [User: BronzeBeard, Post #128]

Cause: This occurs during a hard reboot/shutdown on the CM5. The power management system enters an undefined state.

"The Dim Green Light of Death happens when you do a hard reboot by holding down the power button. The green light becomes dim instead of turning off. Then no matter what you do, you can not boot the system back up until the batteries are unplugged." [User: BronzeBeard, Post #128]

Resolution:

  1. Remove Power: You must physically remove the batteries to reset the state.

    "If you get the dim green light you pretty much have to open it up and take out the battery." [User: REDROBRC, Post #99] "hard reboots on the CM5 still require removal of the batteries." [User: Rex, Post #131]

Prevention: Ensure your EEPROM configuration includes the POWER_OFF_ON_HALT=1 setting. (See Installation & First Boot: Post-Boot Configuration).

12.3 Audio Noise and Crackling (CM5)

Symptoms:

  • "Scraping/scratching sounds out the speakers." [User: NumbaWon, Post #205]
  • "Pulsing when the processing gets higher or when there are more screen redraws." [User: NumbaWon, Post #205]
  • "Overpowers system volume when playing videos." [User: giftsonjebin, Post #243]

Cause: This is a hardware power issue specific to the CM5 and the main board voltage regulation.

"It’s a power issue with the main board and CM5. once you start getting to about 50% it starts and gets worse as the voltage drops." [User: Rex, Post #209]

Workaround:

  • Keep the battery charged above 50%.

    "The crackling is a known issue when the battery is roughly 50%, and gets worse as it gets lower." [User: bitnotfound, Post #244]

  • (See Power Management & Battery for more workarounds).

12.4 Boot Loops and First Boot Behavior

Symptoms:

  • The device shows the Clockwork logo, some terminal lines, goes black, and restarts.
  • "I either see nothing or the Clockwork logo followed by a few terminal lines and then it just goes black." [User: NAA, Post #147]

Explanation: This is normal behavior for the first boot of the Bookworm 6.12 image.

"On first boot the device will boot, resize the FS, create ssh keys, then reboot. This is normal and you don’t want to interrupt this process." [User: Rex, Post #148]

12.5 CM5 Lite SD Card Detection (Hot-Swap Trick)

Symptoms:

  • CM5 Lite fails to boot (no backlight).
  • EEPROM updates cannot be applied because the SD card is not detected.

Diagnostic/Workaround: If the CM5 is not detecting the SD card to apply necessary EEPROM modifications, a "hot-swap" method may force detection.

  1. Boot the uConsole.
  2. Wait approximately 30 seconds.
  3. Remove and reinsert the SD card while the device is still on.

"Basically, my problem was that the CM5 wasn’t detecting the SD card, so I couldn’t apply any EEPROM modifications. However, I found that if you boot up the uConsole, wait about 30 seconds, then remove and reinsert the SD card while the device is still on, it works." [User: Quixote, Post #524]

12.6 Display Initialization Failure (Backlight ON)

Symptoms:

  • Backlight is on (screen glows), but no image appears.
  • SSH or VNC access works.
  • dmesg logs show: 
    panel-cwu50-cm5 1f00130000.dsi.0: CWU50: Failed to read power mode on first attempt, restarting initialization…
panel-cwu50-cm5 1f00130000.dsi.0: CWU50: Panel failed initialization after multiple attempts
    [User: thoughtfix, Post #16]

Cause: The CM5 display driver is a work in progress and may fail to initialize the panel correctly on cold boots.

"The CM5 drivers are still a work in progress and the panel doesn’t work quite right yet." [User: Rex, Post #14]

Resolution:

  • Perform a reboot (See 12.1 Blind Reboot).

    "If you can SSH in reboot the screen has a better success rate on reboots then cold boots." [User: Rex, Post #14]

  • If using a CM4, ensure the kernel is updated.

    "I can confirm cold boots are working now as well as screen blanking." [User: n1f7, Post #117] sudo apt reinstall clockworkpi-kernel [User: Rex, Post #109]

Frequently Asked Questions (FAQ)

Display & Graphics

Q: My screen is rotated 90 degrees (sideways) after booting or logging in. How do I fix this? A: If you are using the standard Desktop Environment (DE), you can use the built-in utility.

  • Run raindrop and rotate the panel [User: Rex, Post #60].

Q: I get a black screen on the LCD, but the device seems to be on (backlight is visible). A: This is a known "panel failure problem" where the driver fails to initialize the display on cold boots. The best workaround is to reboot blindly.

  • Blind Reboot Method: "Wait a bit then hit the power button once hit the down arrow key and hit enter" [User: Rex, Post #31].
  • Alternatively, "double tap the power button to shutdown" [User: Rex, Post #77].
  • (See Display & Graphics Subsystem).

Power & Battery

Q: The battery indicator shows 100% or incorrect values (e.g., 100-98%) even after running for an hour. A: The Power Management Unit (PMU) needs to be calibrated for your specific batteries [User: Rex, Post #19].

Q: How do I calibrate the battery? A: Follow this procedure:

  1. Charge the device to 100%.
  2. Activate the calibrate function: 
    echo 1 | sudo tee /sys/class/power_supply/axp20x-battery/calibrate
  3. Drain the device to power off.
  4. Charge the device to 100% [User: Rex, Post #21].

Note: If you check the status, a value of 48 means it is calibrating [User: Rex, Post #140].

Q: My CM5 uConsole makes a crackling noise. A: This is a known issue with the CM5 and the main board power delivery. It typically starts when the battery is roughly 50% and gets worse as the voltage drops [User: bitnotfound, Post #244; User: Rex, Post #209]. (See Power Management & Battery).

Input Devices (Keyboard & Trackball)

Q: The keyboard layout is wrong (e.g., the | key types # or ~). A: The Raspberry Pi OS defaults to the GB (Great Britain) keyboard layout. You must reset it to US.

  • Run sudo raspi-config.
  • Select (6 Localization Options).
  • Select (L3 Keyboard) and set it to US keyboard [User: Rex, Post #73; User: Eduardolicious, Post #26].

Q: How do I get the scroll feature working on the trackball? A: The keyboard firmware is separate from the OS and runs on a microcontroller. You need to flash updated firmware to enable features like scrolling [User: Rex, Post #153].

Compute Module 5 (CM5) Specifics

Q: My CM5 Lite will not boot from the SD card. A: The CM5 Lite requires updated firmware (released after 2025-01-06) and specific EEPROM settings to handle SD card timing quirks.

Q: Some applications (like Wine or Box86) are not working on the CM5. A: By default, the CM5 uses the 2712 kernel which has a 16k page size. Legacy software often requires a 4k page size.

  • To switch to the 4k kernel, add kernel=kernel8.img to the [all] section in /boot/firmware/config.txt [User: Rex, Post #31; User: Rex, Post #199].

General System

Q: I updated the kernel and now my screen is rotated or things are broken. A: Ensure you are installing the specific ClockworkPi kernel packages, not generic Raspberry Pi ones.

  • Run: sudo apt install clockworkpi-kernel clockworkpi-cm-firmware [User: Rex, Post #54].
  • If you lose the battery applet or other specific features, you may need to "flash the new image" rather than just updating [User: Rex, Post #57].

Q: Can I use the Raspberry Pi Imager "Custom Settings" (gear icon) to set up WiFi/SSH before flashing? A: No. "Raspberry Pi Imager will cause image not to boot if you apply custom settings" [User: Rex, Post #1]. The image uses a custom first-boot script to resize the filesystem and generate keys [User: Rex, Post #148].

Credits & Resources

This section compiles the essential download locations for operating system images, source code repositories for kernel development, hardware expansion packages, and acknowledgments for the community members who have developed the software and hardware modifications detailed in this guide.

14.1 OS Image Download Mirrors

The ClockworkPi-Bookworm-6.12.y images are the recommended standard for 2026, supporting both uConsole (CM3/CM4/CM5) and DevTerm hardware. These images are built using Pi-Gen, feature a unified dark mode, sane charging defaults, and include the necessary kernel patches maintained by Rex.

14.2 Source Code & Repositories

This subsection details the repositories required for system recovery, kernel compilation, and hardware expansion.

  • Kernel Source Tree (rpi-6.12.y branch): Maintained by Rex, this repository contains the kernel source with ClockworkPi drivers pre-marked for compilation in bcm2711_defconfig or bcm2712_defconfig. github.com/ak-rex [User: Rex, Post #1]

    Compilation Note: For users wishing to cross-compile the kernel themselves, the following procedure is recommended:

    git clone --depth=1 https://github.com/ak-rex/ClockworkPi-linux
cd ClockworkPi-linux
KERNEL=kernel8
make ARCH=arm64 CROSS_COMPILE=aarch64-linux-gnu- bcm2711_defconfig
make -j"$(nproc)" ARCH=arm64 CROSS_COMPILE=aarch64-linux-gnu- Image headers modules dtbs
make -j"$(nproc)" ARCH=arm64 CROSS_COMPILE=aarch64-linux-gnu- bindeb-pkg

    [User: Rex, Post #319]

  • Raspberry Pi USB Boot (CM5 Recovery): Essential for recovering CM5 Compute Modules with corrupted EEPROMs. If your CM5 is stuck in the bootloader or unresponsive, this tool allows you to re-flash the bootloader via a host PC. github.com/raspberrypi/usbboot

    Recovery Instructions: See CM5 Specific Configuration: Fixing Corrupted EEPROM via USB Boot for detailed steps. [User: Chad_Vavra, Post #854; User: undefinedman, Post #627]

  • HackerGadgets AIO Support: For users utilizing the HackerGadgets All-In-One (AIO) extension board (RTL-SDR/LoRa/GPS/RTC/USB Hub), a dedicated package is available to automate configuration on Bookworm systems.

    • Repository/Package: hackergadgets-uconsole-aio-board
    • Installation: 
      sudo apt update && sudo apt --install-recommends install hackergadgets-uconsole-aio-board

    [User: Rex, Post #609]

  • Official uConsole Repository: The manufacturer's repository containing stock images, original kernel patches, keyboard firmware, and hardware schematics. github.com/clockworkpi/uConsole [User: white-round-square, Post #157]

  • QMK Firmware: Community-ported QMK firmware for the uConsole keyboard, offering advanced mapping capabilities. github.com/clockworkpi/uConsole/wiki/Simple-uConsole-keyboard-flashing-tool [User: white-round-square, Post #157]

14.3 Key Contributors

The stability and feature set of the Bookworm 6.12.y ecosystem rely on the contributions of specific community members. Their work ensures continued support for the uConsole and DevTerm well into 2026.

  • Rex: The primary maintainer of the Bookworm OS images, the APT repository, and the kernel patches that enable functionality like the external WiFi antenna and 4G card activation (uconsole-4g enable).
  • Paragonnov: Developed the pre-configured eeprom.bin recovery files and methods specifically for fixing CM5 Lite boot issues and NVMe boot ordering. [User: paragonnov, Post #45]
  • Vileer & Lululvlv: Developers of the community NVMe adapter boards (USB 3.0 speed) and associated boot configurations, allowing for expanded storage capabilities on the uConsole. [User: Rex, Post #762]
  • Olly: Developer of the QMK firmware port for the uConsole keyboard, allowing for custom keymaps and macros. [User: Rex, Post #629]
  • Chad_Vavra & Undefinedman: Identified and documented the specific usbboot recovery steps required to unbrick CM5 EEPROMs when standard flashing fails. [User: Chad_Vavra, Post #856]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment