aiov2_ctl

A lightweight power and feature control client for the HackerGadgets AIO v2 board (GPIO-based fork).

This tool controls onboard hardware (GPS, LoRa, SDR, USB power rails) via direct GPIO access using pinctrl, and supports both CLI and system tray GUI modes.

---

What this tool does

aiov2_ctl directly toggles GPIO pins mapped to hardware enable lines in order to:

• Enable / disable onboard hardware modules
• Query current on/off state
• Monitor overall board power usage
• Provide a tray-based GUI for quick toggling
• Optionally auto-start the GUI on login (XDG desktops)

GPIO state reporting model:

• Runtime state is truth-first from pinctrl get level parsing (hi/lo)
• If level is -- (not driven), state falls back to explicit per-pin boot defaults
• No global GPIO inference heuristics are used

---

Requirements

• HackerGadgets uConsole AIO v2 Upgrade Kit
  https://hackergadgets.com/products/uconsole-upgrade-kit?variant=47038702682286
• uConsole running Debian / Raspberry Pi OS (Bookworm or Trixie recommended)
• Python 3.9+
• pinctrl available on the system (used for direct GPIO control)
• Desktop environment with system tray support (for GUI mode)

---

1) System dependencies

Install required system packages:

sudo apt update
sudo apt install -y python3 python3-pyqt6 git

---

2) Install aiov2_ctl (system-wide)

The recommended install location is /usr/local/bin.

Clone the repository anywhere (e.g. your home directory), then install:

git clone https://github.com/hackergadgets/aiov2_ctl.git
cd aiov2_ctl

sudo python3 ./aiov2_ctl.py --install

Sanity check:

aiov2_ctl
aiov2_ctl --status

Install also enables the rail boot apply service:

• aiov2-rails-boot.service
• Applies configured rail boot states at startup

---

3) Optional: HackerGadgets AIO Companion Apps

This step is optional and not required for basic GPIO or GUI usage.

Install preconfigured AIO apps

sudo aiov2_ctl --add-apps

Installs and configures:

• hackergadgets-uconsole-aio-board — Core AIO v2 integration (GPIO, power rails, RTC support, services, and uConsole-specific configuration)
• meshtastic-mui — Meshtastic graphical UI for LoRa / Meshtastic devices (depends on the AIO package)
• sdrpp-brown — Preconfigured SDR++ build for the uConsole (RF scanning/listening via SDR)
• tar1090 — ADS-B aircraft tracking web UI (visualises planes from your SDR feed)
• pygpsclient — GPS monitoring and diagnostics GUI (position, satellites, NMEA data)

This pulls in supporting services (RTC, GPIO helpers, and desktop menu entries) used by the HackerGadgets AIO ecosystem.

---

Remove AIO apps (cleanup / testing)

sudo aiov2_ctl --remove-apps

Removes the above packages and runs apt autoremove.
Useful for testing reinstallation or returning to a minimal setup.

---

Sync system time to RTC

sudo aiov2_ctl --sync-rtc

Writes the current system time to the hardware RTC using hwclock -w.

Only run this after confirming system time is correct (e.g. via NTP).

---

4) CLI usage

Show current GPIO state:

aiov2_ctl

Show detailed status (including battery / power rail info):

aiov2_ctl --status

Enable or disable a feature:

aiov2_ctl <FEATURE> <on|off>

Supported features:

• GPS
• LORA
• SDR
• USB

Examples:

aiov2_ctl GPS on
aiov2_ctl LORA off
aiov2_ctl SDR on

Rail boot-state commands

Configure per-feature rail state to apply at boot:

aiov2_ctl --boot-rail <FEATURE> on
aiov2_ctl --boot-rail <FEATURE> off
aiov2_ctl --boot-rail <FEATURE> status
aiov2_ctl --boot-rails-status

Examples:

aiov2_ctl --boot-rail SDR on
aiov2_ctl --boot-rail LORA off
aiov2_ctl --boot-rails-status

Notes:

• Boot rail settings are applied by aiov2-rails-boot.service
• --boot-rail ... on|off may require sudo escalation depending on context

---

5) Power monitoring

Live power monitor (Ctrl+C to exit):

aiov2_ctl --power

Compact live GPIO + power line (single-line view):

aiov2_ctl --watch

---

6) GUI mode (system tray)

Start the tray-based GUI:

aiov2_ctl --gui

Behaviour

• Left-click: opens a small status window (Wayland-safe)
• Right-click: opens tray menu to toggle hardware
• Right-click also includes a Rails on boot submenu for per-feature boot preferences
• Power usage is updated once per second
• GUI must not be run as root

GUI menu distinction:

• Main feature toggles = live rail state now
• Rails on boot toggles = persisted boot preference

---

7) Autostart GUI on login (recommended)

For desktop environments that support XDG autostart (LXQt, XFCE, GNOME, etc.), this is handled automatically.

Enable autostart

aiov2_ctl --autostart

Creates:

~/.config/autostart/aiov2_ctl.desktop

Disable autostart

aiov2_ctl --no-autostart

Notes

• Autostart is per-user, not system-wide
• Never run autostart commands as root
• Uses /usr/local/bin/aiov2_ctl --gui
• Includes a small startup delay to allow GPIO and desktop services to settle

---

8) Updating aiov2_ctl

Pull the latest version and reinstall automatically:

aiov2_ctl --update

Behaviour:

• Git operations are never run as root
• The tool escalates only for the install step
• Clean exit if already up to date
• Update path re-runs install, including boot rail service install/enable

---

Safety notes

• GPIO writes happen immediately
• Assumes exclusive control of AIO v2 GPIO pins
• Battery telemetry comes directly from kernel power_supply
• Power deltas below ~0.05 W are considered noise

State source visibility:

• Use AIOV2_CTL_DEBUG=1 aiov2_ctl --status to show source labels:
  • (pinctrl) for direct hi/lo
  • (boot_default) for -- fallback
  • (unknown) for unparseable/failed reads

Maintained for HackerGadgets uConsole AIO v2 users.