How to create GUIv2 UI Plugins

This guide explains how to add custom GUIv2 QML pages to the GUIv2. Currently UI Plugins load only on the local GX display; WASM/browser support is planned.

Summary

• Add a GUIv2 UI Plugin by creating a small JSON file and QML pages inside your app folder on the device.
• Supported targets today:
  • Settings -> Integrations (settings pages)
  • Settings -> Devices -> (devicelist pages tied to a device ID)

Requirements

• Venus OS v3.70~45 or newer.
• Venus OS root access

How it works (high level)

1. Put your app in /data/apps/available/<your-app>.
2. Create a subfolder gui-v2 in the app folder to hold the generated JSON file.
3. Put your QML pages anywhere under the app (commonly a folder like gui-v2-source).
4. Use the helper script gui-v2-plugin-compiler.py (on the device and in the GUIv2 repository) to generate the JSON file.
5. Copy the generated JSON into the gui-v2 folder and enable the app (symlink into /data/apps/enabled).

Step-by-step

1. Folder layout on the GX device

   • Example app name: my-app
   • App root: /data/apps/available/my-app
   • UI plugin file: /data/apps/available/my-app/gui-v2
   • QML source files (example): /data/apps/available/my-app/gui-v2-source

2. Create your QML pages

   • Write QML pages for the UI you want to show.
   • Place them under your app folder (e.g. gui-v2-source).
   • See example QML example pages here and some QML example items here.

3. Generate the UI plugin JSON

   • SSH to the GX device and cd into your QML source folder:

     cd /data/apps/available/my-app/gui-v2-source

   • Run the plugin compiler script located in /opt/victronenergy/gui-v2.

   • Examples:

     For device-list pages (pages shown for a specific device ID)

     python3 /opt/victronenergy/gui-v2/gui-v2-plugin-compiler.py \
       --name my-app \
       --min-required-version v1.2.13 \
       --devicelist 0x106 DeviceListExample_CellVoltages.qml 'Cell Voltages' \
       --devicelist 0x106 DeviceListExample_CellTemperatures.qml 'Cell Temperatures' \
       --devicelist 0x106 DeviceListExample_ComponentError.qml 'Invalid Customisation'

     For settings pages (shown under Settings -> Integrations)

     python3 /opt/victronenergy/gui-v2/gui-v2-plugin-compiler.py \
       --name my-app \
       --min-required-version v1.2.13 \
       --settings SimpleExample_PageSettingsSimple.qml

   • The script outputs a JSON file named <your-app>.json (e.g. my-app.json).

4. Install the UI plugin file

   • Copy the generated JSON to the gui-v2 folder:

     cp -f my-app.json /data/apps/available/my-app/gui-v2

5. Enable the app (make it visible to the system)

   • Create a symlink under /data/apps/enabled that points to /data/apps/available/<your-app>:

     ln -s /data/apps/available/my-app /data/apps/enabled/my-app

6. Check the GUI

   • Settings -> Integrations shows the integration entry (if you added settings pages).
   • Settings -> Devices -> will show any devicelist pages for the device ID(s) you registered.
   • Note: If you only added devicelist pages, the integration navigation item may not be clickable — open pages under the matching device instead.

7. To disable the app again

   • Remove the symlink

     rm /data/apps/enabled/my-app

Tips and notes

• Use the correct device ID (hex) for devicelist pages (e.g. 0x106)
• Set a sensible --min-required-version to prevent loading on incompatible GUI versions
• Test pages on the GX display (WASM/browser loading support is not yet available)
• Translatable strings are now also possible, check the example pages for more detailed information
• QML page examples: https://github.com/victronenergy/gui-v2/tree/main/examples
• QML item examples: https://github.com/victronenergy/gui-v2/blob/main/pages/settings/debug/PageSettingsDemo.qml