Skip to content

uConsole Setup Guide CM5 Configuration

github-actions[bot] edited this page Nov 15, 2026 · 1 revision

Note

Reviewed October 31, 2026. The conservative CM5 setup procedure is retained. A detected NVMe device does not itself establish NVMe boot support; confirm carrier support, EEPROM boot order and a verified bootable image before changing startup storage. Read the official Raspberry Pi Compute Module documentation and uConsole review. No automated hardware validation was performed.

Rex's Kali or Trixie + HackerGadgets AIO v2 Board + HackerGadgets Battery & NVMe Board

A complete setup guide for building a field-deployable hacking and SIGINT platform using the ClockworkPi uConsole with a Raspberry Pi CM5, Rex's community images (Kali Linux or Debian Trixie), and the HackerGadgets AIO v2 extension board.

Important

CM5 desktop regression: Earlier script revisions can disrupt the working Rex desktop. Start with CM5 display recovery if you have a rotated screen or a blank desktop after login. The proposed v1.4 installer preserves session and boot configuration, skips upgrades, and makes AIO installation opt-in. Hardware validation is pending. See script usage. Do not layer Kali repositories onto Debian or replace the image's desktop with plain Labwc.


Table of Contents


๐ŸŽฏ Purpose

Step-by-step build instructions for the CM5 variant of the uConsole + AIO v2 platform specifically - GPIO pin behavior, config.txt overlays, and known failure modes here are CM5-specific (e.g., /dev/ttyAMA0 instead of /dev/ttyS0, dtparam=uart0 instead of enable_uart=1, native PCIe NVMe support) and will not match the CM4. Use this file (not CM4-SETUP.md) when your board is a Raspberry Pi Compute Module 5.

โš™๏ธ Function

Organized as the same 14 sequential numbered steps as CM4-SETUP.md (flash OS โ†’ pre-flight hardening โ†’ system update โ†’ Kali tools โ†’ aiov2_ctl install โ†’ AIO v2 board package โ†’ GPS/LoRa/RTC/SDR configuration โ†’ GPIO power control โ†’ WiFi/LAN pentesting setup โ†’ NVMe battery board), followed by reference tables and a Troubleshooting section. Differs from CM4-SETUP.md in GPIO/UART/RTC device-tree overlays, GPS serial port path, SDR default boot state (HIGH on CM5 vs OFF on CM4), and native PCIe NVMe support; differs from README.md, which is the folder-level index rather than a build walkthrough. Every step is also implemented as an idempotent shell script in scripts/uconsole-cm5-setup.sh (see scripts/README.md).

๐Ÿ† Goal

A working CM5-based uConsole with the AIO v2 board fully configured - RTL-SDR, LoRa/Meshtastic, GPS, and RTC all functioning, GPIO power control operational, and WiFi/LAN pentesting tooling installed - without the CM5-specific pitfalls (SD boot failures on old EEPROM, UART/RTC overlay mismatches) this guide's troubleshooting section already documents.

๐Ÿ“‹ When to Use

When building or repairing a CM5-based uConsole from scratch, or when a specific step (e.g., Meshtastic not starting, GPS not getting a fix, CM5 lite SD card not booting) needs a manual fix outside of running the automation script.


Hardware Overview

This guide assumes the following hardware stack:

Component Detail
Handheld ClockworkPi uConsole
Compute Module Raspberry Pi CM5 (with HackerGadgets CM5 adapter board)
Extension Board HackerGadgets AIO v2 (RTL-SDR / LoRa / GPS / RTC / USB Hub)
OS Rex's Kali Linux or Rex's Debian Trixie (6.12.y kernel)
WiFi Adapter External monitor-mode capable adapter (CM5 onboard WiFi does NOT support monitor mode)

What the AIO v2 Provides

Feature Chip / Spec
RTL-SDR R828D + TCXO, 100 kHzโ€“1.74 GHz, 5V bias tee for active antennas/LNAs
LoRa SX1262, 860โ€“960 MHz, 22 dBm max output, TCXO, Meshtastic-ready
GPS Multi-mode (GPS/BDS/GNSS), active and passive antenna support
RTC PCF85063A + CR1220 battery backup
USB Hub External USB-C port + internal USB-C + pin header
RJ45 Ethernet Gigabit (requires HackerGadgets adapter board from Upgrade Kit)

Critical Assembly Note: When installing the AIO v2 board, ensure the ribbon cable is oriented correctly as shown in the HackerGadgets documentation. Never plug in the charger if the ribbon cable is installed the wrong way - incorrect installation will damage the uConsole mainboard.

AIO v2 GPIO Map (Verified Against HackerGadgets Official Docs)

These are the AIO v2 control GPIOs. (AIO v1 used different pins for LoRa and Internal USB - make sure you're working with v2 hardware.)

Peripheral GPIO Notes
GPS 27 Pull HIGH to enable
LoRa 16 Pull HIGH to enable
SDR (RTL-SDR) 7 Pull HIGH to enable. On CM5, this defaults HIGH at boot - RTL-SDR is detected immediately. On CM4, it defaults OFF.
Internal USB (USB-C + pin header) 23 Pull HIGH to enable
GPS PPS (output) 6 Optional, for microsecond-accurate NTP timing

Choosing Your OS: Kali vs Trixie

Rex maintains community images for the uConsole that include a custom kernel (record the actual version with uname -r) with all necessary hardware patches for the uConsole display, keyboard, and trackball. His images also include a custom APT repository required for the hackergadgets-uconsole-aio-board package - that package is not available on stock ClockworkPi or upstream Kali images.

Rex's images include several conveniences that this guide relies on:

  • Auto-expanding root filesystem on first boot (no raspi-config needed)
  • linux-headers shipped with the kernel (no separate DKMS headers install)
  • A dedicated "drivers" block at the bottom of /boot/firmware/config.txt with instructions for enabling overlays

CM5 special note from Rex: The AIO board package was developed primarily for CM5 because enabling SPI for Meshtastic on CM5 needs additional plumbing to keep the display panel working. Using the official hackergadgets-uconsole-aio-board package is therefore strongly recommended on CM5 - the manual route is risky.

Path A: Rex's Kali Image

Choose the native Kali image when you need Kali metapackages. Check which tools are included in that specific release. Preserve its desktop/session configuration and review package upgrades before applying them.

Path B: Rex's Trixie Image

Use Debian 13 Trixie with its intended Debian/Raspberry Pi/Rex repositories. Install tools available for that distribution. For Kali-only workflows, use a separate Kali installation instead of adding Kali rolling to Debian. The old tool allowlist did not prevent unrelated Kali packages from becoming upgrade candidates. Kali repository guidance

Other Rex Images

Image Best For
Bookworm 6.12.y Maximum stability, daily driver, most community-tested
DragonOS Dedicated SDR/RF analysis (now based on Debian Trixie)

Tip: Consider keeping Rex's DragonOS on a second SD card for dedicated SDR/RF analysis sessions. It ships with GNU Radio, SDR++, and a broader RF toolkit than the AIO board package alone.


Step 1: Flash the OS

Download Your Image

Kali:

  • Thread: Kali 6.12.y for the uConsole and DevTerm
  • Look for the MEGA or Google Drive link in the first post
  • Use the image labeled with kernel 6.12.67 or later (required for the new uConsole screens)
  • Default credentials: kali / kali

Trixie:

Flash the Image

Rex's specific guidance from the forum threads: use Raspberry Pi Imager directly on the compressed .xz file, and do not apply any custom settings. Custom settings (hostname, WiFi, SSH) from Pi Imager will cause Rex's images to fail to boot.

  1. Install Raspberry Pi Imager on your host machine.
  2. In Pi Imager:
    • Operating System: "Use Custom" โ†’ select the downloaded .xz file directly (do not decompress first)
    • Storage: your microSD card (16 GB minimum, 32+ GB recommended)
    • Click Write. When prompted about custom settings, choose No / Skip.
  3. Insert the microSD card into the uConsole and boot.

Linux/dd alternative: If you prefer the command line, decompress with xz -d <image>.xz first, then sudo dd if=<image>.img of=/dev/sdX bs=4M status=progress conv=fsync. Pi Imager is what Rex specifically recommends, though.

CM5 lite SD card boot issue: If you have a CM5 lite and the SD card won't boot, you likely need an EEPROM update. See Troubleshooting โ†’ CM5 lite SD boot fails before getting frustrated - this is a known issue with a documented fix.

First Boot

Power on. Rex's images auto-expand the root filesystem on first boot and then reboot once - let that complete. After the second boot:

  • Log in using the credentials supplied or established by the exact trusted image. Never assume a fixed factory password; change initial credentials promptly.
  • Open a terminal

Record the working baseline and back up before package changes. Proceed to Step 2.


Step 2: First Boot - Preserve the Working Image

Verify the desktop, panel, input and orientation before setup. Record /etc/os-release, uname -r and the image release; back up storage and configuration. Preserve the supplied LightDM/AccountsService session choices, cryptsetup configuration, Python protections and raspberrypi-sys-mods.

Do not switch to a generic Labwc session to preempt a hypothetical failure. If the desktop is already broken, use CM5 display recovery before installing more packages.

Step 3: System Update and Initial Configuration

Review the image maintainer's current update guidance. After checking repository configuration, inspect a simulation before considering an upgrade:

sudo apt-get update
apt-get -s upgrade

These commands refresh indexes and simulate changes; they do not perform a system upgrade. Check proposed changes to the kernel, firmware, compositor, display manager and desktop packages. No pin file or forced-overwrite setting makes every upgrade safe. The v1.4 setup script skips system upgrades.

Set your timezone with sudo dpkg-reconfigure tzdata and update your account password using passwd as needed.

Step 4: Security Tools for Your Distribution

On Debian, use tools packaged for Debian and the intended image repositories. Do not add Kali sources or install Kali metapackages on this host. On a native Kali image, review the selected metapackage and optionally use:

sudo bash ./uconsole-cm5-setup.sh --install-kali-tools

This requires the reviewed v1.4 script. Existing v1.3 state must be investigated before continuing; --reset is not a rollback.

Steps 5โ€“11 and the boot-overlay reference apply only to fitted AIO hardware. Confirm the current vendor instructions for your board/image before executing hardware changes. The v1.4 script does not automate these manual boot edits or source installers.

Step 5: Install aiov2_ctl (GPIO Control Tool)

aiov2_ctl is HackerGadgets' official control tool for the AIO v2 board. It must be installed before the main AIO board package to resolve pathing correctly.

# Install build/runtime dependencies
sudo apt update
sudo apt install -y python3 python3-pyqt6 git

# Clone and install
git clone https://github.com/hackergadgets/aiov2_ctl.git /opt/aiov2_ctl
cd /opt/aiov2_ctl
sudo python3 ./aiov2_ctl.py --install

# Fix PATH for root environments
sudo ln -sf /usr/local/bin/aiov2_ctl /usr/bin/aiov2_ctl

# Verify
command -v aiov2_ctl && aiov2_ctl --status

The install enables the aiov2-rails-boot.service so boot-rail settings persist across reboots.

Fix .pygpsclient venv ownership (required for aiov2_ctl --gui)

python3 ./aiov2_ctl.py --install creates a Python venv at ~/.pygpsclient/ but runs as root, so the venv files are root-owned. The regular user can't launch --gui until ownership is corrected and PyQt6 is installed inside the venv:

# Fix ownership so your regular user owns the venv
sudo chown -R $USER:$USER ~/.pygpsclient

# Install PyQt6 inside the venv (not the system Python)
~/.pygpsclient/bin/pip3 install --ignore-installed PyQt6 --break-system-packages

# Verify
aiov2_ctl --status

Note: aiov2_ctl --gui requires a physical display. Running it over SSH (with no DISPLAY) will fail. Use --autostart and reboot to launch the tray icon natively from the desktop.


Step 6: Install the AIO v2 Board Package

Only for a physically installed, supported HackerGadgets AIO board. Check the current Rex package instructions and inspect the proposed installation:

sudo apt-get update
apt-get -s --no-remove --install-recommends install hackergadgets-uconsole-aio-board

If the repository/package is unavailable or dependencies conflict, stop and resolve the image compatibility problem. Do not inject Bookworm libraries, purge/retry automatically, force file overwrites, or create a pcmanfm-pi symlink as a desktop workaround.

The reviewed v1.4 script's --with-aio option installs this package through APT. Package maintainer scripts can still change configuration; --no-remove does not prevent that. Back up first and test the desktop afterward. Follow upstream instructions separately for optional controller, Meshtastic and ADS-B features.


Step 7: Configure GPS (CM5)

CM5-Specific GPS Path

On CM5, the GPS serial port is /dev/ttyAMA0 (CM4 uses /dev/ttyS0).

Enable the UART in config.txt

Per HackerGadgets' CM5 setup guide, add the following to /boot/firmware/config.txt:

dtparam=uart0

Free the Serial Port from the Console

Edit /boot/firmware/cmdline.txt and remove console=serial0,115200:

sudo sed -i 's/console=serial0,115200 \?//' /boot/firmware/cmdline.txt

Add Your User to the dialout Group

sudo usermod -a -G dialout $USER

Log out and back in (or reboot) for the group change to take effect.


Step 8: Configure LoRa / Meshtastic

Enable SPI1 in config.txt

Add to /boot/firmware/config.txt (CM5 does not need dtparam=spi=on like CM4):

dtoverlay=spi1-1cs

Disable the conflicting devterm-printer service

sudo systemctl stop devterm-printer.service
sudo systemctl disable devterm-printer.service

Power on the LoRa module

aiov2_ctl LORA on

Step 9: Configure RTC (CM5)

The CM5 requires disabling its internal RTC and mapping the AIO board's RTC over i2c_csi_dsi0.

Enable the RTC overlay (CM5)

Add to /boot/firmware/config.txt:

dtparam=rtc=off
dtparam=i2c_arm=on
dtoverlay=i2c-rtc,pcf85063a,i2c_csi_dsi0

Reboot, then verify:

sudo hwclock -r
sudo aiov2_ctl --sync-rtc

Step 10: Configure SDR

Blacklist the DVB-T kernel driver

The Linux kernel will try to claim the RTL2832U/R828D chip as a TV tuner. Blacklist it:

echo "blacklist dvb_usb_rtl28xxu" | sudo tee /etc/modprobe.d/blacklist-rtl.conf
sudo rmmod dvb_usb_rtl28xxu 2>/dev/null

Note: On CM5, the SDR rail defaults to HIGH at boot, so the device is immediately available.


Step 11: GPIO Power Control

Configure peripherals to auto-enable at boot:

aiov2_ctl --boot-rail GPS on
aiov2_ctl --boot-rail LORA on
aiov2_ctl --boot-rail SDR on

# Verify
aiov2_ctl --boot-rails-status

Step 12: WiFi Pentesting Setup

The CM5's onboard WiFi does not support monitor mode. Use an external USB WiFi adapter.

# Install DKMS driver for RTL8812AU
sudo apt install realtek-rtl88xxau-dkms -y
sudo dkms status | grep rtl88

# Enable monitor mode (wlan1 = external; wlan0 = onboard)
sudo airmon-ng start wlan1
iwconfig wlan1mon

Step 13: LAN Pentesting via RJ45

The AIO v2 provides Gigabit Ethernet via the RJ45 port (requires Upgrade Kit adapter).

# Plug into a target switch, request DHCP
sudo dhclient eth0

# Verify connectivity
ip addr show eth0

# Run Responder for credential capture
sudo responder -I eth0 -wrf

Step 14: NVMe Battery Board Setup

NVMe Software Configuration (CM5)

CM5 exposes PCIe, but the carrier and NVMe Battery Board must support it, and the exact board/image configuration matters. Consult the board vendor before editing config.txt; for applicable images this overlay enables the PCIe controller:

dtparam=pciex1=on

Reboot and verify:

lspci                          # Does PCIe enumerate the storage adapter?
lsblk -o NAME,SIZE,MODEL,FSTYPE,MOUNTPOINTS  # Confirm the actual drive
sudo rpi-eeprom-config           # If supported; inspect BOOT_ORDER, no edit

Important: /dev/nvme0n1 appearing does not mean the bootloader will boot from it. Do not clone/format NVMe or change EEPROM boot order without backups and a tested recovery route. The official Compute Module boot guide describes EEPROM boot configuration and its risks.


CM5-Specific Notes and Limitations

Item CM5 Detail
GPS Serial Port /dev/ttyAMA0 (CM4 uses /dev/ttyS0)
GPS UART Config Requires dtparam=uart0 in config.txt (CM4 uses enable_uart=1)
SPI Config Requires dtoverlay=spi1-1cs (CM4 also needs dtparam=spi=on)
RTC Config Must disable internal RTC (dtparam=rtc=off) + remap i2c0 via i2c_csi_dsi0
SDR Boot State Defaults HIGH (ON) at boot (CM4 defaults OFF)
Serial Console Must remove console=serial0,115200 from cmdline.txt for GPS
PCIe / NVMe Native PCIe support.

AIO v2 Board: Hardware Reference

Antenna Connectors

Label Purpose Antenna Type
SDR RTL-SDR receiver Wideband, or frequency-specific
LoRa SX1262 transceiver 433 or 915 MHz (region-dependent)
GPS GPS/BDS/GNSS receiver Active or passive GPS antenna

aiov2_ctl: Full Command Reference

aiov2_ctl                           # Show current GPIO state
aiov2_ctl --status                  # Detailed status (GPIO + battery + power)
aiov2_ctl <FEATURE> <on|off>        # Toggle: GPS, LORA, SDR, USB
aiov2_ctl --power                   # Live power monitor (Ctrl+C to exit)
aiov2_ctl --watch                   # Compact live GPIO + power line
aiov2_ctl --gui                     # Launch system tray GUI
aiov2_ctl --autostart               # Enable GUI autostart on login
aiov2_ctl --boot-rail <FEAT> on     # Set peripheral to enable at boot
aiov2_ctl --boot-rails-status       # Show all boot rail configurations
aiov2_ctl --sync-rtc                # Write system time to hardware RTC

Meshtastic Web Interface

Meshtasticd's web server is enabled by the AIO board package's default config.

  1. Browse to https://localhost on the uConsole.
  2. Accept the self-signed cert ("Proceed to localhost (unsafe)").
  3. In the connection dialog, enter localhost (not meshtastic.local) and click Connect.
  4. Config โ†’ LoRa โ†’ Region: set your region (US for 915 MHz). Different regions cannot communicate.
  5. Config โ†’ LoRa โ†’ Modem Preset: Set to LongFast (Standard slot 20 for US).

Boot Automation

Complete /boot/firmware/config.txt Additions (CM5)

These are the overlay/parameter lines this guide adds to the bottom of Rex's config.txt:

# === AIO v2 Board Configuration (CM5) ===

# Enable UART0 for GPS on /dev/ttyAMA0
dtparam=uart0

# SPI for LoRa (SX1262)
dtoverlay=spi1-1cs

# Disable internal RTC and map AIO RTC (PCF85063A)
dtparam=rtc=off
dtparam=i2c_arm=on
dtoverlay=i2c-rtc,pcf85063a,i2c_csi_dsi0

# PCIe for NVMe (only if using NVMe Battery Board)
dtparam=pciex1=on

Troubleshooting

CM5 lite SD card boot fails

CM5 lite modules shipped with older EEPROMs may fail to boot from the SD card. You likely need an EEPROM update (firmware must be newer than 2025-01-06). Check the ClockworkPi forums for CM5 recovery/flashing guides.

"Failed to start session" at LightDM login

Use CM5 display recovery to identify the selected session, package changes and startup errors. Restore the matching image configuration; do not assume generic Labwc, a forced package version, or suppressing an authentication agent is a universal fix.

GPS shows no data on /dev/ttyAMA0

  • Confirm dtparam=uart0 is in /boot/firmware/config.txt and you've rebooted.
  • Confirm console=serial0,115200 is removed from /boot/firmware/cmdline.txt.
  • Confirm GPS power rail is enabled: aiov2_ctl GPS on.

LoRa / Meshtasticd fails to start

  • Verify devterm-printer.service is disabled: sudo systemctl status devterm-printer.service.
  • Confirm SPI overlay in config.txt: dtoverlay=spi1-1cs.
  • Check LoRa power rail: aiov2_ctl LORA on.

libfm ABI Mismatch (symbol lookup error)

For this ABI mismatch, follow the CM5 display recovery procedure and restore the compatible image packages; avoid forcing an unrelated library version.

aiov2_ctl --gui fails: "PyQt6 is not installed"

aiov2_ctl --install creates a Python venv at ~/.pygpsclient/ as root, so the files are root-owned after the script runs. Fix it:

# Restore ownership
sudo chown -R $USER:$USER ~/.pygpsclient

# Install PyQt6 inside the venv
~/.pygpsclient/bin/pip3 install --ignore-installed PyQt6 --break-system-packages

# Now try the GUI
aiov2_ctl --gui

Also ensure libxcb-cursor0 is installed - the Qt6 XCB platform plugin won't load without it:

sudo apt install -y libxcb-cursor0

aiov2_ctl --gui errors over SSH

The GUI requires a live display server ($DISPLAY / Wayland socket). Running it from an SSH session fails because there is no display. Use --autostart instead and reboot:

aiov2_ctl --autostart
sudo reboot

GDBus error: polkit-mate agent conflict on Labwc

For this PolKit error, inspect the session's authentication-agent configuration using CM5 display recovery; do not disable the agent indiscriminately.

Resources and Links

Related Files


๐Ÿ“„ Source: uConsole/CM5-SETUP.md | โœ๏ธ Suggest an edit | โฌ…๏ธ Back to uConsole

Clone this wiki locally