Skip to content

uConsole

github-actions[bot] edited this page Nov 15, 2026 · 2 revisions

Complete build guides for the ClockworkPi uConsole with HackerGadgets AIO v2 board - SDR, LoRa, GPS, and pentesting in your pocket

Part of the ULTIMATE CYBERSECURITY MASTER GUIDE

CM4 CM5 AIO v2

Important

CM5 screen rotated or desktop blank after setup? See CM5 display recovery. Earlier setup scripts can alter the desktop and mix Kali packages into Debian. The current CM5 v1.4 workflow preserves the working desktop by default; device testing is pending. CM4 legacy automation was replaced with the v2.0 read-only-by-default script and the repair utility now requires explicit --apply, and its dangerous cross-distribution/forced-overwrite behavior has been retired. See CM4 safety review. Physical CM4/CM5 hardware validation remains necessary.

๐ŸŽฏ Purpose

Complete build and configuration guides for the ClockworkPi uConsole with HackerGadgets AIO v2 board - a pocket-sized Linux handheld optimized for SDR, LoRa, GPS, and field pentesting use.

โš™๏ธ Function

Documents CM4 and CM5 module configurations, HackerGadgets AIO v2 + Battery/NVMe board setup, Kali Linux and Debian Trixie post-flash configuration, driver installation (WiFi, Bluetooth, audio, display), and automated setup scripts for reproducible deployments.

๐Ÿ† Goal

A fully configured, field-ready uConsole running on Kali or Trixie with all hardware working: RTL-SDR, LoRa, GPS, external WiFi adapter, NVMe storage, and the HackerGadgets power board.

๐Ÿ“‹ When To Use

  • Initial uConsole build after flashing Kali or Trixie to the CM4/CM5 module
  • Rebuilding a uConsole after a failed update or storage wipe
  • Configuring a new HackerGadgets AIO v2 board with battery and NVMe expansion
  • Reference for driver troubleshooting (WiFi chipset, audio, display brightness)

๐Ÿ“‹ Table Of Contents


๐ŸŽฏ Overview

This directory contains complete, step-by-step build guides and automated deployment scripts for turning a ClockworkPi uConsole into a field-deployable hacking and SIGINT platform using the HackerGadgets AIO v2 extension board.

What This Covers:

  • โš™๏ธ Automated setup scripts (uconsole-cm4-setup.sh, uconsole-cm5-setup.sh) with image-specific prerequisites and recovery guidance
  • ๐Ÿ“ก RTL-SDR setup and configuration (100 kHz โ€“ 1.74 GHz)
  • ๐Ÿ“ป LoRa / Meshtastic mesh networking (SX1262)
  • ๐Ÿ›ฐ๏ธ GPS receiver configuration and PPS timing
  • โฐ Hardware RTC with battery backup (PCF85063A)
  • ๐Ÿ”Œ NVMe storage via the HackerGadgets NVMe Battery Board
  • ๐ŸŒ Gigabit Ethernet via RJ45 (Upgrade Kit required)
  • ๐Ÿ“ถ WiFi pentesting with external monitor-mode adapters
  • ๐Ÿ”ง GPIO power control via aiov2_ctl
  • ๐Ÿง OS setup for both Kali Linux and Debian Trixie (Rex's images)
  • โš ๏ธ Known package conflicts and automated fixes (cryptsetup, LightDM, Trixie dependency drift, libfm ABI mismatch, libxcb-cursor0 for Qt6 GUI, .pygpsclient venv ownership, PolKit agent conflict on Labwc)

๐Ÿ“‚ Setup Guides

Guide Compute Module Description
CM4-SETUP.md Raspberry Pi CM4 Safer staged CM4 setup. v2.0 setup script is read-only by default; AIO and native Kali installs are opt-in.
CM5-SETUP.md Raspberry Pi CM5 Complete CM5 setup - Features the uconsole-cm5-setup.sh automated installer, USB 3.0, and native PCIe configurations.
ParrotOS Guide Raspberry Pi CM5 Guide for installation on ParrotOS vs Kali; use at your own risk! This is a work in progress

Which guide should I follow? If you already have your hardware, follow the guide matching your compute module. If you're buying new, see the comparison table below.


๐Ÿ–ฅ๏ธ Hardware Stack

Core Components

Component Detail
Handheld ClockworkPi uConsole
Compute Module Raspberry Pi CM4 or CM5 (with HackerGadgets adapter board)
Extension Board HackerGadgets AIO v2
OS Rex's Kali Linux or Rex's Debian Trixie (6.12.y kernel), *ParrotOS work in progress
WiFi Adapter External monitor-mode capable adapter (RTL8812AU recommended)

Optional Components

Component Detail
NVMe Battery Board HackerGadgets NVMe Battery Board (18650 or LiPo variant)
Upgrade Kit HackerGadgets Upgrade Kit (required for RJ45, USB 3.0, NVMe)
AC1200 WiFi Card HackerGadgets AC1200 USB-C WiFi Card (sold separately)

โš–๏ธ Cm4 Vs Cm5 - Quick Reference

Feature CM4 CM5
GPS Serial Port /dev/ttyS0 /dev/ttyAMA0
USB Speed USB 2.0 only USB 3.0 (with Upgrade Kit)
GPIO Boot State All peripherals OFF GPIO 7 (SDR) ON by default
RTC Config dtoverlay=i2c-rtc,pcf85063a dtparam=rtc=off + dtoverlay=i2c-rtc,pcf85063a,i2c_csi_dsi0
Serial Console Remove console=serial0,115200 from cmdline.txt Remove console=serial0,115200 from cmdline.txt
SPI Conflict Disable devterm-printer.service Disable devterm-printer.service
Onboard WiFi No monitor mode No monitor mode
Community Maturity Most tested, most stable Newer, improving rapidly
PCIe Gen 2 (via adapter board) Native PCIe support
NVMe EEPROM Usually fine, some older units need update Native NVMe boot support
Internal RTC None (uses AIO v2's PCF85063A) Has internal RTC (must disable for AIO v2's RTC)

Which Should I Buy?

Choose CM4 if: You want the most stable, community-tested configuration with the fewest surprises. Best for first-time uConsole builders.

Choose CM5 if: You want USB 3.0 for external adapters, native PCIe for NVMe, and the newer BCM2712 SoC. Better long-term investment, but occasional rough edges.


๐Ÿง Kali Os Options

These guides cover two distinct operating-system families, not two flavors of Kali. Avoid cross-distribution APT source mixing:

Path A: Rex's Kali Image

Use a native Kali image for Kali metapackages. Check the image release's actual included tools and update guidance; preserve its desktop configuration.

Path B: Rex's Trixie Image

Use Debian 13 Trixie with the repositories intended for that image. Do not add Kali rolling to Debian. The old tool allowlist did not block all Kali system packages. Kali repository guidance

Other Rex Images

Image Best For
Bookworm 6.12.y Maximum stability, daily driver
DragonOS Dedicated SDR/RF analysis (GNU Radio, full RF toolkit)

๐Ÿ“ก Aio V2 Board Capabilities

Integrated Peripherals

Peripheral Chip / Spec GPIO Control
RTL-SDR R828D + TCXO, 100 kHz โ€“ 1.74 GHz, 5V bias tee GPIO 7
LoRa SX1262, 860โ€“960 MHz, 22 dBm, TCXO, Meshtastic-ready GPIO 16
GPS Multi-mode GPS/BDS/GNSS, active + passive antenna GPIO 27
RTC PCF85063A + CR1220 battery backup I2C (always on)
Internal USB USB-C + pin header hub GPIO 23
RJ45 Ethernet Gigabit (requires Upgrade Kit adapter board) Always on

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

Gpio Control Tool - aiov2_ctl

All peripherals are controlled via GPIO using aiov2_ctl (GitHub):

aiov2_ctl                           # Show current GPIO state
aiov2_ctl <FEATURE> <on|off>        # Toggle: GPS, LORA, SDR, USB
aiov2_ctl --status                  # Detailed status (GPIO + battery + power)
aiov2_ctl --gui                     # Launch system tray GUI
aiov2_ctl --boot-rail <FEAT> on     # Auto-enable at boot
aiov2_ctl --sync-rtc                # Write system time to hardware RTC

๐Ÿ›ก๏ธ Cm4 Review & Safest Starting Point

The CM4 safety and migration review explains why the old CM4 installer was retired. For an existing CM4, start with:

bash uConsole/scripts/uconsole-cm4-setup.sh --help
bash uConsole/scripts/uconsole-cm4-setup.sh --status

These actions do not change package sources, the display manager, EEPROM, storage or radio power. When adding actual AIO hardware, follow the CM4 setup guide and confirm with the vendor's AIO v2 documentation.

๐Ÿ”ง Common Setup Sequence (The 6-Phase Approach)

uConsole CM5 six phase safe optional installation workflow

Conceptual CM5 setup summary; CM4 and different boards require their own preflight and documentation.

For CM5 v1.4, the defaults preserve the working image and optional installations require flags. See script usage and recovery instructions. The CM4 v2.0 procedure is different: read-only preflight by default with optional reviewed package installations. See the CM4 script reference.

Phase CM5 v1.4 behavior
Preflight Validate OS/hardware/source configuration and back up configuration
Update Skip system upgrades; optional hostname change
Kali tools Opt-in, native Kali only
AIO Opt-in Rex package installation for fitted hardware
Peripherals Preserve boot settings; optional chipset-appropriate DKMS package
Finalize Package audit; manual reboot/desktop/hardware verification

Default setup does not install the complete AIO ecosystem. Follow the current board vendor instructions for additional hardware configuration. Software tests are not proof of a working CM5 desktop.


โš ๏ธ Security & Legal Disclaimer

๐Ÿ”ด Authorized Use Only

โš ๏ธ LEGAL AND ETHICAL USE ONLY โš ๏ธ

This platform includes tools and capabilities for:

โœ… AUTHORIZED USES:
   โ€ข Penetration testing with explicit written authorization
   โ€ข Red team operations with organizational approval
   โ€ข Security assessments with client permission
   โ€ข RF monitoring and analysis on authorized frequencies
   โ€ข Mesh networking on licensed or unlicensed bands
   โ€ข Security research in isolated lab environments
   โ€ข Educational purposes with proper supervision
   โ€ข CTF competitions and authorized challenges

๐Ÿšซ STRICTLY PROHIBITED:
   โ€ข Unauthorized penetration testing or network access
   โ€ข Intercepting communications without authorization
   โ€ข Transmitting on frequencies without proper licensing
   โ€ข WiFi deauthentication attacks on networks you don't own
   โ€ข Any use violating the Computer Fraud and Abuse Act (CFAA)
   โ€ข Any illegal or unethical activities

RF & Radio Compliance

  • LoRa / Meshtastic: Operates on ISM band (915 MHz US). No license required for low-power operation within FCC Part 15 limits.
  • RTL-SDR: Receive-only device. Legal to receive in most jurisdictions, but intercepting certain communications (cellular, encrypted, private) may violate wiretapping laws.
  • WiFi Pentesting: Monitor mode and packet injection are legal ONLY on networks you own or have explicit written authorization to test.

Warranty Disclaimer

These guides are provided "AS IS" without warranty of any kind.

THE AUTHORS:
โ€ข Are not responsible for damages from guide use
โ€ข Do not warrant techniques will work in all environments
โ€ข Are not liable for legal consequences of misuse
โ€ข May update content without notice

USERS ACKNOWLEDGE:
โ€ข They use these guides at their own risk
โ€ข They are responsible for obtaining authorization
โ€ข They must comply with all applicable laws
โ€ข They are liable for their testing activities

๐Ÿ“š Resources

Forum Threads

Resource URL
Rex's Kali Image https://forum.clockworkpi.com/t/kali-6-12-y-for-the-uconsole-and-devterm/14463
Rex's Trixie Image https://forum.clockworkpi.com/t/trixie-6-12-y-for-the-uconsole-and-devterm/19457
Rex's Bookworm Image https://forum.clockworkpi.com/t/bookworm-6-12-y-for-the-uconsole-and-devterm/15847
AIO Board Package https://forum.clockworkpi.com/t/hackergadgets-aio-board-package/17875
Updated Images (New Screens) https://forum.clockworkpi.com/t/updated-images-for-new-uconsole-screens/21666

Documentation & Guides

Resource URL
AIO v2 Setup Guide https://hackergadgets.com/pages/hackergadgets-uconsole-rtl-sdr-lora-gps-rtc-usb-hub-all-in-one-extension-board-setup-guide
aiov2_ctl GitHub https://github.com/hackergadgets/aiov2_ctl
uConsole GitHub (Official) https://github.com/clockworkpi/uConsole
Meshtastic Firmware Releases https://github.com/meshtastic/firmware/releases

Products

Product URL
AIO v2 Board https://hackergadgets.com/products/uconsole-aio-v2
uConsole Upgrade Kit https://hackergadgets.com/products/uconsole-upgrade-kit
NVMe Battery Board https://hackergadgets.com/products/nvme

๐Ÿ”— Quick Links

Internal Links


๐Ÿ“Š Repository Statistics

๐Ÿ“ Setup Guides: CM4, CM5, CM5 recovery and experimental Parrot + multiple setup/repair scripts
๐Ÿ“– Covers: OS setup, AIO v2 board, NVMe, WiFi, LoRa, GPS, SDR, RTC
๐Ÿ”„ Section reviewed: October 31, 2026 (physical deployment validation outstanding)
๐Ÿ‘ฅ Maintained by: Pacific Northwest Computers (PNWC)
๐Ÿ“ Status: Active & Growing

๐Ÿค Contributing

To contribute to the uConsole section:

  1. Follow the 4-header standard: ## ๐ŸŽฏ Purpose, ## โš™๏ธ Function, ## ๐Ÿ† Goal, ## ๐Ÿ“‹ When to Use after every H1
  2. Add a ## Related Files section at the bottom with bidirectional links
  3. Use hyphens (-) not em-dashes
  4. Verify all commands against the current hardware/firmware version before adding
  5. Include RF compliance notes for any SDR or radio transmission guidance
  6. Note the exact hardware revision and OS version tested against

๐Ÿ“– Build Responsibly: Authorization is MANDATORY for Pentesting

A pocket-sized SIGINT and pentesting platform - use it ethically and legally.

Repository: ULTIMATE CYBERSECURITY MASTER GUIDE

Maintained by: Pacific Northwest Computers


โš ๏ธ CRITICAL: These are ATTACK TECHNIQUES - Written authorization is REQUIRED โš ๏ธ

โš ๏ธ Unauthorized use is a FEDERAL CRIME with up to 10 years imprisonment โš ๏ธ

โš ๏ธ ALWAYS obtain explicit written authorization before using any technique โš ๏ธ

โญ Star this repo if you find it useful! โญ

Related Files


๐Ÿ“‘ All Pages in uConsole

Guides & Reference

scripts


๐Ÿ“‚ Folder: uConsole | โœ๏ธ Suggest an edit | ๐Ÿ—บ๏ธ Browse by Topic

Clone this wiki locally