Skip to content

uConsole Setup Scripts

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

๐ŸŽฏ Purpose

Post-flash setup and recovery references for ClockworkPi uConsole systems. Choose the script for your compute module and read its current limitations before running it.

Important

CM5 rotation/blank desktop reports: Use CM5 display recovery before rerunning an old installer. The current CM5 v1.4 workflow avoids the risky cross-distribution and desktop changes by default. Hardware validation is pending. The legacy CM4 v1.x installer was replaced by a conservative CM4 v2.0 script; old backup copies of v1.x must not be run. See safety review.

๐Ÿ“‚ Scripts

Script Scope
uconsole-cm5-parrot-setup.sh Experimental Parrot CM5 post-flash setup; requires existing Parrot. Usage and limits
uconsole-cm5-setup.sh Conservative CM5 setup, proposed v1.4; preserves the image's desktop and boot configuration
uconsole-cm4-setup.sh CM4 v2.0 read-only preflight by default; optional AIO package on Debian or toolkit on native Kali, with configuration backup and APT simulation
uconsole-repair.sh CM4/CM5 boot-overlay and historical desktop diagnosis read-only by default; explicit --apply required for changes, not a general desktop recovery tool

โš™๏ธ Cm5 V1.4 Behavior

Phase Behavior
preflight Preserve desktop, authentication and encryption configuration
update Skip system upgrade; optionally set hostname
kali_tools Install requested metapackage only on native Kali
aio Install Rex's AIO board package only with --with-aio
peripherals Leave boot overlays unchanged; optional Wi-Fi DKMS install
finalize Audit package state; require manual device verification

Environment/source checks and a root-only configuration/package snapshot run before selected operations, including --phase. Default execution does not install packages. It saves a configuration snapshot and successful completion state; it is not a full backup or desktop repair.

Automatic source installation of aiov2_ctl, legacy library downloads, Meshtastic/ADS-B bootstraps, hardware rail programming and direct overlay edits were removed. Use current HackerGadgets instructions and Rex package guidance for fitted hardware. The candidate intentionally reduces the old installer's scope.

APT installations use --no-remove and stop on failure. Dependency upgrades and package-maintainer script changes are still possible. Review on spare media before broad use.

๐Ÿš€ Cm4 V2.0 Usage

Caution

Earlier CM4 v1.x automation mixed Kali and Debian repositories, forced package overwrites and executed unchecked remote installers. Do not run the old v1.x script. The version below doesn't perform desktop, EEPROM, NVMe or GPIO changes, nor does it guarantee AIO hardware works on every image.

# From repository root; read-only checks
bash uConsole/scripts/uconsole-cm4-setup.sh --help
bash uConsole/scripts/uconsole-cm4-setup.sh --status

# Optional dry-run: verifies hardware, OS and repository family
bash uConsole/scripts/uconsole-cm4-setup.sh --with-aio --dry-run

# If, and only if, the AIO v2 board is fitted to a supported Debian/RPi OS:
sudo bash uConsole/scripts/uconsole-cm4-setup.sh --with-aio

# On native Kali only (not on Debian Trixie):
sudo bash uConsole/scripts/uconsole-cm4-setup.sh --kali-tools

# Separate configuration-only backup, not a substitute for disk imaging
sudo bash uConsole/scripts/uconsole-cm4-setup.sh --snapshot

The installer refuses hardware other than CM4 and Debian systems containing Kali sources. It requires confirmation for writes, snapshots selected configuration, simulates APT and refuses planned removals. It does not install aiov2_ctl from a moving Git branch or write config.txt. Follow CM4 manual hardware steps, review notes and current HackerGadgets instructions after verifying hardware/image compatibility.

๐Ÿš€ Cm5 V1.4 Usage

Inspect the currently checked-out CM5 script and confirm --help reports v1.4. Do not use an older v1.3 script from a stale local copy.

bash ./uconsole-cm5-setup.sh --help
sudo bash ./uconsole-cm5-setup.sh --dry-run
sudo bash ./uconsole-cm5-setup.sh

# Fitted AIO hardware only
sudo bash ./uconsole-cm5-setup.sh --with-aio

# Native Kali only
sudo bash ./uconsole-cm5-setup.sh --install-kali-tools
Option Meaning
--with-aio / --skip-aio Enable/disable AIO package installation; default off
--install-kali-tools / --skip-kali-tools Enable/disable native Kali metapackage; default off
--kali-meta=PKG Select and enable a kali-* metapackage on native Kali
--install-wifi-dkms / --skip-wifi-dkms Enable/disable driver package; default off; confirm chipset and matching headers first
--hostname=NAME Optional hostname change
--phase=PHASE Run one phase; do not advance completion state
--dry-run Print planned operations without logs, backups or state writes
--yes Accept the initial confirmation; does not bypass safety checks
--status Read completion state
--reset Archive state markers; does not undo package/configuration changes

Supported environment options: INSTALL_AIO, INSTALL_KALI_TOOLS, INSTALL_WIFI_DKMS, KALI_METAPACKAGE, HOSTNAME_NEW, DRY_RUN, ASSUME_YES. Boolean values must be yes or no; sudo may filter environment variables, so CLI flags are preferred.

๐Ÿงญ Existing Installations

v1.4 refuses automatic continuation of legacy setup state. Diagnose and recover the affected system first. --reset is not a rollback. Active Kali sources on Debian are rejected even for resumed/forced operations. Removing sources does not downgrade already installed packages.

The new installer runs selected operations in one invocation rather than automatically resuming across three reboots. Reboot manually when appropriate after optional package installations; test login, orientation, panel and input before adding more software.

๐Ÿฉบ Cm4/Cm5 Repair Tool: Diagnose First

# Read-only by default; must currently be run as root for full diagnosis
sudo bash uConsole/scripts/uconsole-repair.sh
sudo bash uConsole/scripts/uconsole-repair.sh --diagnose

# Only after reviewing exact diagnosis, backups and restore plan:
sudo bash uConsole/scripts/uconsole-repair.sh --apply

--yes alone does not permit writes. With --apply, the repair script can still modify boot overlays, APT preferences and desktop state, so it is not a safe substitute for restoring a known-good image or the CM5 display recovery procedure. Do not use it as an automatic fix for an unexplained display problem.

โœ… Verification

From the repository root:

bash -n uConsole/scripts/uconsole-cm4-setup.sh
bash -n uConsole/scripts/uconsole-repair.sh
bash -n uConsole/scripts/uconsole-cm5-setup.sh
python3 -m unittest discover -s uConsole/tests -v

Regression tests use isolated fixtures; they do not install packages or exercise physical hardware. Follow the device validation checklist before release.


๐Ÿ  uConsole ยท ๐Ÿ“˜ CM5 guide ยท ๐Ÿ–ฅ๏ธ Display recovery


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

Clone this wiki locally