Documentation

Everything you need to install, configure, and manage the uConsole with uconsole-cloud.

#Installation

On your uConsole (arm64 Debian Bookworm):

curl -s https://uconsole.cloud/install | sudo bash

This adds the GPG-signed APT repository and installs the uconsole-cloud package. Then run the setup wizard:

uconsole setup

Future updates arrive automatically via sudo apt upgrade.

What gets installed

uconsole CLI at /usr/bin/uconsole
46 management scripts in /opt/uconsole/scripts/
Curses TUI at /usr/bin/console
Flask web dashboard at /opt/uconsole/webdash/
Systemd services and timers (enabled by setup wizard)
Nginx HTTPS reverse proxy config for uconsole.local
Avahi mDNS advertisement

#Setup Wizard

uconsole setup walks through 9 steps:

Hardware Detection — Scans for AIO expansion board (SDR, LoRa, GPS, RTC), WiFi method, compute module

System Configuration — CPU frequency cap, low battery shutdown voltage

Webdash Password — Sets a bcrypt-hashed password for the local web dashboard

Hotspot Configuration — WiFi fallback AP SSID (default: uConsole)

Cloud Link — Optional — generates a device code to link with uconsole.cloud

Backup Configuration — Schedule for automated backups (daily/weekly/manual)

Enable Services — Starts webdash, status timer, backup timer, update timer

SSL Certificate — Generates a self-signed cert with SANs for uconsole.local

Summary — Shows what was configured and how to access everything

The wizard is re-runnable. Existing config values are preserved — just hit Enter to keep them.

#CLI Reference

uconsole setupRun the interactive setup wizard (hardware detect, passwords, services, cloud link)

uconsole linkLink device to uconsole.cloud via code auth (cloud-only, no wizard)

uconsole pushPush device status to the cloud now

uconsole statusShow current config, timer status, last push time

uconsole doctorDiagnose services, SSL, nginx, connectivity — reports pass/fail

uconsole restoreRun restore.sh from your backup repo to rebuild the device

uconsole unlinkRemove cloud config (keeps services installed)

uconsole updateUpdate via APT (package mode) or re-download scripts (standalone)

uconsole versionShow installed version

uconsole helpShow all commands

#Architecture

uConsole (arm64, Debian)              Cloud (Vercel)
┌─────────────────────────┐       ┌─────────────────────────┐
│                         │       │                         │
│  /opt/uconsole/         │       │  uconsole.cloud         │
│  ├── bin/               │       │                         │
│  │   ├── uconsole  CLI  │       │  Upstash Redis          │
│  │   └── console   TUI  │       │  (device telemetry)     │
│  ├── scripts/           │       │         │               │
│  │   └── system/        │       │         ▼               │
│  │       └── push ──────────→   │  Next.js 16 SSR         │
│  ├── webdash/      POST │       │  (Server Components)    │
│  │   └── app.py ◄─┐    │       │         │               │
│  └── lib/          │    │       │         ▼               │
│               nginx │    │       │    Dashboard            │
│               :443  │    │       │                         │
│                     │    │       │  /apt/ (package repo)   │
└─────────────────────┘    │       └─────────────────────────┘
                           │
Phone / Browser            │
┌─────────────────┐        │
│ uconsole.cloud  │ ◄──────── Vercel CDN
│ uconsole.local  │ ◄──┘
└─────────────────┘

Device → Redis → Dashboard. The device pushes telemetry every 5 minutes. The cloud dashboard reads it on page load. No browser polling. Data persists indefinitely.

Cloud is optional. Everything works offline — the local webdash, TUI, and all management scripts run without internet.

#Telemetry

push-status.sh collects from sysfs and procfs every 5 minutes:

Category	Metrics
Battery	capacity, voltage, current, status, health
CPU	temperature, load average, core count
Memory	total, used, available
Disk	total, used, available, percent
WiFi	SSID, signal dBm, quality, bitrate, IP
Screen	brightness, max brightness
AIO Board	SDR, LoRa, GPS fix, RTC sync
Hardware	expansion module, component detection
Webdash	running, port
System	hostname, kernel, uptime

#Local Web Dashboard

The Flask web dashboard runs at https://uconsole.local (mDNS) or your device's IP. It provides:

Live system stats via SSE (Server-Sent Events)
Browser-based terminal (xterm.js + PTY)
Script execution dashboard (60+ scripts)
System management panels
PWA — installable on phone

HTTPS uses a self-signed certificate with SANs. On first visit, accept the certificate warning or install the cert as a trusted profile on your phone/laptop.

WiFi Fallback AP

When no known WiFi network is available, the device creates a fallback access point (default SSID: "uConsole"). Connect your phone to this AP to access the webdash at https://10.42.0.1 — no internet required.

#Cloud Dashboard

uconsole.cloud shows your device status from anywhere. Sign in with GitHub, link your device with a code, and get:

Live device telemetry (battery, CPU, memory, WiFi, AIO board)
Persistent status — survives reboots, shows staleness
Backup coverage across 9 categories with sparklines
Package inventory, browser extensions, scripts
Hardware manifest (expansion module detection)
Same-network detection — direct link to local webdash

Device Code Auth

Run uconsole link on the device. It shows an 8-character code and QR code. Enter the code at uconsole.cloud/link to connect. No passwords to type on a tiny keyboard.

#Scripts

46 management scripts organized in 5 categories under /opt/uconsole/scripts/.

network/(5 files)

hotspot.sh, network.sh, wifi-fallback.sh, wifi.sh, lib.sh

power/(11 files)

battery.sh, battery-test.sh, cellhealth.sh, charge.sh, cpu-freq-cap.sh, fix-battery-boot.sh, fix-voltage-cutoff.sh, low-battery-shutdown.sh, pmu-voltage-min.sh, power.sh, lib.sh

radio/(8 files)

aio-check.sh, esp32.sh, esp32-marauder.sh, gps.sh, lora.sh, lora_helper.py, sdr.sh, lib.sh

system/(5 files)

backup.sh, push-status.sh, restore.sh, update.sh, lib.sh

util/(18 files)

audit.sh, boot-check.sh, config.py, config.sh, console.sh, crash-log.sh, dashboard.sh, discharge-test.sh, diskusage.sh, hardware-detect.sh, integration-test.sh, smoke-test.sh, storage.sh, trackball-scroll.py, webdash-ctl.sh, webdash-info.sh, webdash.sh, lib.sh

#TUI Modules

Curses-based terminal interface launched via console. 9 category tabs, 53 native tools. Supports keyboard (arrows, vim keys) and gamepad input.

framework

Main loop, menus, rendering

monitor

Real-time CPU, RAM, temp gauges

network

WiFi switcher, hotspot, fallback

radio

GPS globe, FM radio

adsb

Global ADS-B map, layers, hi-res fetch

marauder

ESP32 Marauder WiFi/BLE toolkit

telegram

Terminal Telegram client (tg + tdlib)

services

Timer config, push interval

tools

Git panel, notes, calculator, stopwatch

games

Watch Dogs Go, minesweeper, snake, tetris, 2048, ROMs

watchdogs

Watch Dogs Go launcher with auto-install

launcher

Shared detached-spawn helper

files

File browser

config_ui

Theme picker, view mode

workspace-monitor

Labwc workspace detection

#Webdash API

46 routes served by the Flask webdash at https://uconsole.local.

Category	Endpoints
Auth	/login, /setup-password, /api/set-password, /logout
Dashboard	/, /api/logo, /api/stats, /api/public/stats
Config	/api/config, /api/config/brightness, /api/config/git-remote, /api/config/timezone
Timers	/api/timers, /api/timer-schedule/<name>
Monitoring	/api/processes, /api/logs/<source>, /api/connections, /api/services
Wiki	/api/wiki (GET/POST/DELETE)
WiFi	/api/wifi/scan, /api/wifi/connect, /api/wifi/disconnect
Scripts	/api/run/<script> (POST), /api/stream/<script> (SSE)
Battery	/api/battery-test/chart, /api/battery-test/start
Hardware	/api/esp32, /api/gps, /api/sdr, /api/lora (GET + push POST)
Terminal	SocketIO: pty-spawn, pty-input, pty-resize, pty-output, pty-exit
Static	/favicon.png, /uconsole.crt, /manifest.json, /sw.js

#Services

4 systemd services and 3 timers, managed by the setup wizard.

uconsole-webdash.serviceFlask dashboard on :8080, Restart=always

uconsole-status.service + timerPush telemetry every 5 minutes

uconsole-backup.service + timerDaily backup at 3:00 AM

uconsole-update.service + timerWeekly update check, Sunday 4:00 AM

nginxHTTPS reverse proxy on :443, self-signed cert, CORS for uconsole.cloud

#Security

Authentication: NextAuth v5 + GitHub OAuth on the cloud side. bcrypt-hashed passwords on the local webdash.

Device tokens: 90-day UUID v4 tokens stored at /etc/uconsole/status.env (chmod 600, owned by device user).

Sessions: Cryptographically random session tokens (secrets.token_hex), server-side session store with 30-day TTL.

Local TLS: Self-signed cert with SANs (DNS:uconsole.local, DNS:uconsole, IP:127.0.0.1). Key readable by nginx (640 root:www-data).

Rate limiting: Device code generation limited to 5 requests per minute per IP.

Input validation: Path traversal blocks, SHA regex, strict repo format validation on all API routes.

Headers: CSP, X-Frame-Options DENY, nosniff, strict Referrer-Policy, restrictive Permissions-Policy.

Process safety: PID range guard (2-4194304) in TUI process manager. AST-based calculator prevents code injection.

Network isolation: Webdash binds 127.0.0.1 only (nginx proxies). CORS whitelist: uconsole.local, uconsole.cloud. PTY auth gate on terminal sessions.

Systemd hardening: PrivateTmp, ProtectSystem=strict, NoNewPrivileges on all service units.

#Troubleshooting

Run the doctor

uconsole doctor

Reports pass/fail for config, services, nginx, SSL, connectivity. Fix what it flags.

Webdash not loading

sudo systemctl status uconsole-webdash
sudo systemctl restart uconsole-webdash
journalctl -u uconsole-webdash -f

Status not pushing to cloud

uconsole status          # check config
uconsole push            # manual push
journalctl -u uconsole-status -n 20

Certificate warnings in Chrome

Chrome requires Subject Alternative Names (SANs). Regenerate the cert by running uconsole setup (Step 8 will regenerate if you delete the old cert first):

sudo rm /etc/uconsole/ssl/uconsole.*
uconsole setup

iOS PWA icon shows letter instead of logo

Safari won't load the favicon from a self-signed cert it doesn't trust. Fix: go to Settings > General > About > Certificate Trust Settings, enable the uconsole.local certificate. Then clear Safari website data (Settings > Safari > Clear History and Website Data). Delete the old PWA from Home Screen and re-add from Safari's share sheet.

Desktop is bare after reboot

The labwc autostart file can get overwritten by system updates, losing pcmanfm, wf-panel, and kanshi entries. Check ~/.config/labwc/autostart has all required entries. Consider adding it to your backup system.

Console keybind missing after apt upgrade

The package installs to /opt/uconsole but your dev tree at ~/pkg may have newer code. Run uconsole update or manually copy from your dev tree.

Webdash scripts return empty

SCRIPTS_DIR resolution may be wrong. Run uconsole doctor and verify /opt/uconsole/scripts/ has the expected scripts. Also check that PATH includes /opt/uconsole/bin.

uConsole won't boot on battery

The AXP228 PMU defaults to a 3.3V undervoltage cutoff. 18650 cells sag below this during boot inrush. Install the battery boot fix from TUI (Power > Power Config > Install Boot Fix) or run sudo bash /opt/uconsole/scripts/power/fix-battery-boot.sh install. This sets a 2.9V cutoff via udev rule, initramfs hook, and shutdown service.

GPS satellite globe shows "No Signal"

The u-blox GPS module needs gpsd's -b flag to stay in NMEA mode for satellite visibility data. The package adds this automatically on install. To fix manually: sudo sed -i '/^GPSD_OPTIONS=/ s/"$/ -b"/' /etc/default/gpsd && sudo systemctl restart gpsd

LoRa SX1262 not detected

The SX1262 is on SPI1 (/dev/spidev1.0), not SPI4. The lora.sh script loads the spi1-1cs overlay on demand and unloads it after use to avoid audio interference. Do not add dtoverlay=spi1-1cs to config.txt permanently.

WiFi fallback AP not starting

NetworkManager connection profile may be missing. Re-run uconsole setup to reconfigure hotspot settings.

Reset everything

sudo apt remove uconsole-cloud    # remove package
sudo apt purge uconsole-cloud     # remove package + config
curl -s https://uconsole.cloud/install | sudo bash  # reinstall

#Contributing

Issues and PRs welcome — especially from uConsole owners who can test on real hardware.

git clone https://github.com/mikevitelli/uconsole-cloud.git
cd uconsole-cloud
npm install
cp frontend/.env.example frontend/.env.local
# Fill in your credentials
npm run dev    # frontend :3000, studio :3333
npm test       # 1,024 tests (211 vitest + 813 pytest)

See CONTRIBUTING.md for details. Power scripts are safety-critical — changes to battery/charge logic require extra review.

Built for the ClockworkPi uConsole.

GitHub · Dashboard · Link Device · Device Linking Flow