How kwindrem/guimods works
Project Type and Purpose
• This is neither a conventional full-stack web app nor a compiler. It’s an open-source GUI modification (“GuiMods”) package for the VenusOS embedded UI on Victron Energy devices (CCGX, panels, remote consoles).
• It supplies QML “overrides” and Python D-Bus services to enhance the stock UI (dark mode, new overviews, gauges, relay and generator controls, external transfer switch support).
File Structure Analysis
• Top-level scripts:
• ExtTransferSwitch.py – Python service entry point for external transfer-switch logic.
• services/ExtTransferSwitch/… – runit scripts to launch and supervise the above service on target device.
• FileSets/: Contains UI asset bundles organized by firmware version:
• PatchSource – QML and Python “.patch” files and originals, used by SetupHelper to generate patched QML for each target firmware.
• AlternateOriginals & VersionIndependent – supplemental and reusable QML/UI components.
• v3.xx folders – “complete” sets of QML overlays for specific VenusOS firmware versions.
• Configuration files:
• ReadMe – documents features, options, installation.
• setup, packageDependencies, version – metadata for PackageManager and SetupHelper.
Insights from README
• High-level architecture is described: QML overrides loaded in place of built-in GUI pages; Python services interact with VenusOS D-Bus to monitor and control external hardware (transfer switch, generator, relays).
• SetupHelper is a prerequisite installer that applies these patches and configures services.
Main Components & Interactions (
a. Data Sources & Device Interfaces
• Victron hardware: inverter/charger (Multi/Quattro), battery, PV charger/inverter, alternators, relays, tanks, temperature sensors.
• Data bus: VenusOS D-Bus (message bus exposing device metrics, status, control endpoints).
b. Business Logic & Services
• Python D-Bus modules in PatchSource (dbus_systemcalc.py, dbus_generator.py, dbus_*.py) – adapt or extend VenusOS system calculations and expose custom properties.
• ExtTransferSwitch service – listens on a programmed digital input and issues D-Bus commands to switch AC-input current limit and source type.
• runit scripts – supervise the Python service (services/ExtTransferSwitch/run & log/run).
• SetupHelper integration – scans PatchSource file trees, applies .patch files to original QML, and writes out version-specific overrides in FileSets/v3.xx.
c. Presentation Layer (UI)
• QML override files (main.qml, PageMain.qml, Overview*.qml, Detail*.qml, Tile*.qml) organized under FileSets for each firmware version.
• VersionIndependent QML – shared components (e.g., gauges, tiles, utility JS) loaded from a common path.
• The QML engine in VenusOS picks up these overrides (via search path ordering configured by PackageManager).
d. Configuration & Control
• User settings in Device List → Settings → Display & language → GuiMods menu control which overlays and enhancements to load at runtime.
• Settings are saved via VenusOS configuration services and read by SetupHelper and/or Python modules if needed.
Architectural Patterns & Design Principles
• Patch/Override pattern: Original UI pages remain intact; GuiMods supplies a parallel file tree of QML assets that override by matching filenames.
• Version abstraction: FileSets/v3.xx maintain complete sets per firmware version, while VersionIndependent holds shared components.
• Separation of concerns:
• UI declarative layer (QML) is strictly for presentation.
• Python D-Bus modules offer data transformation and control logic.
• runit services handle long-running tasks (transfer-switch monitoring).
• Extensibility: New UI variants can be added by dropping new QML files under FileSets, and new services via services/.
• A notation of versioning strategy (multiple v3.xx directories fed by patches).
• The runit service grouping (services/ExtTransferSwitch).