Repository navigation
uConsole Setup Guide CM5 Configuration
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.
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.
- Hardware Overview
- Choosing Your OS: Kali vs Trixie
- Step 1: Flash the OS
- Step 2: Preserve the Working Image
- Step 3: System Update and Initial Configuration
- Step 4: Distribution Security Tools
- Step 5: Install aiov2_ctl (GPIO Control Tool)
- Step 6: Install the AIO v2 Board Package
- Step 7: Configure GPS (CM5)
- Step 8: Configure LoRa / Meshtastic
- Step 9: Configure RTC (CM5)
- Step 10: Configure SDR
- Step 11: GPIO Power Control
- Step 12: WiFi Pentesting Setup
- Step 13: LAN Pentesting via RJ45
- Step 14: NVMe Battery Board Setup
- CM5-Specific Notes and Limitations
- AIO v2 Board: Hardware Reference
- aiov2_ctl: Full Command Reference
- Meshtastic Web Interface
- Boot Automation
- Troubleshooting
- Resources and Links
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.
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).
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 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.
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) |
| 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.
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 |
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-configneeded) -
linux-headersshipped with the kernel (no separate DKMS headers install) - A dedicated "drivers" block at the bottom of
/boot/firmware/config.txtwith 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-boardpackage is therefore strongly recommended on CM5 - the manual route is risky.
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.
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
| 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.
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:
- Thread: Trixie 6.12.y for the uConsole and DevTerm
- MEGA / Google Drive link in the first post
- Same kernel requirement (6.12.67+)
- Default credentials:
pi/clockworkpi
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.
- Install Raspberry Pi Imager on your host machine.
- In Pi Imager:
-
Operating System: "Use Custom" โ select the downloaded
.xzfile 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.
-
Operating System: "Use Custom" โ select the downloaded
- Insert the microSD card into the uConsole and boot.
Linux/
ddalternative: If you prefer the command line, decompress withxz -d <image>.xzfirst, thensudo 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.
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.
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.
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 upgradeThese 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.
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-toolsThis 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.
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 --statusThe 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 --statusNote:
aiov2_ctl --guirequires a physical display. Running it over SSH (with noDISPLAY) will fail. Use--autostartand reboot to launch the tray icon natively from the desktop.
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-boardIf 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.
On CM5, the GPS serial port is /dev/ttyAMA0 (CM4 uses /dev/ttyS0).
Per HackerGadgets' CM5 setup guide, add the following to /boot/firmware/config.txt:
dtparam=uart0Edit /boot/firmware/cmdline.txt and remove console=serial0,115200:
sudo sed -i 's/console=serial0,115200 \?//' /boot/firmware/cmdline.txtsudo usermod -a -G dialout $USERLog out and back in (or reboot) for the group change to take effect.
Add to /boot/firmware/config.txt (CM5 does not need dtparam=spi=on like CM4):
dtoverlay=spi1-1cssudo systemctl stop devterm-printer.service
sudo systemctl disable devterm-printer.serviceaiov2_ctl LORA onThe CM5 requires disabling its internal RTC and mapping the AIO board's RTC over i2c_csi_dsi0.
Add to /boot/firmware/config.txt:
dtparam=rtc=off
dtparam=i2c_arm=on
dtoverlay=i2c-rtc,pcf85063a,i2c_csi_dsi0Reboot, then verify:
sudo hwclock -r
sudo aiov2_ctl --sync-rtcThe 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/nullNote: On CM5, the SDR rail defaults to HIGH at boot, so the device is immediately available.
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-statusThe 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 wlan1monThe 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 -wrfCM5 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=onReboot 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 editImportant: /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.
| 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. |
| 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 # 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 RTCMeshtasticd's web server is enabled by the AIO board package's default config.
- Browse to
https://localhoston the uConsole. - Accept the self-signed cert ("Proceed to localhost (unsafe)").
- In the connection dialog, enter
localhost(notmeshtastic.local) and click Connect. - Config โ LoRa โ Region: set your region (US for 915 MHz). Different regions cannot communicate.
-
Config โ LoRa โ Modem Preset: Set to
LongFast(Standard slot 20 for US).
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=onCM5 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.
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.
- Confirm
dtparam=uart0is in/boot/firmware/config.txtand you've rebooted. - Confirm
console=serial0,115200is removed from/boot/firmware/cmdline.txt. - Confirm GPS power rail is enabled:
aiov2_ctl GPS on.
- 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.
For this ABI mismatch, follow the CM5 display recovery procedure and restore the compatible image packages; avoid forcing an unrelated library version.
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 --guiAlso ensure libxcb-cursor0 is installed - the Qt6 XCB platform plugin won't load without it:
sudo apt install -y libxcb-cursor0The 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 rebootFor this PolKit error, inspect the session's authentication-agent configuration using CM5 display recovery; do not disable the agent indiscriminately.
- HackerGadgets AIO V1/V2 Setup Guide
- aiov2_ctl GitHub Repo
- Rex's AIO Board Package Thread
- Rex's Trixie Image
- README.md - uConsole section index
- CM4-SETUP.md - CM4 module variant of this guide
- scripts/README.md - Automated scripts to run after following this guide
- ../SDR/sdr.md - Using the RTL-SDR built into the uConsole
๐ Source: uConsole/CM5-SETUP.md | โ๏ธ Suggest an edit | โฌ
๏ธ Back to uConsole
- ๐บ๏ธ Browse by Topic
- ๐ All Repository Files
- ๐งญ Learning Paths
- ๐ Master Guide
- ๐ค Glossary
- โ๏ธ Legal & Disclaimer
๐ Foundations & Learning
๐ก๏ธ Defense & Investigations
- Incident Response
- Open Source Intelligence (OSINT)
- Reverse Engineering
- Operations Security (OPSEC)
- Compliance
โ๏ธ Platforms & Infrastructure
๐ก Hardware, Wireless & Field Projects
- PNWC Cyberdeck
- Hardware Testing
- Hardware Hacking
- Software-Defined Radio
- Wardriving
- uConsole
- Space Security
๐งฐ Assessment & Field Reference
๐ฆ Downloads & Project Resources
๐๏ธ Additional Topics