How to build venus gui v2

Build types

There are various build types:

Build Type	Purpose	Deployment Path	Use Case
GX Device Build	Runs directly on GX devices (e.g., Cerbo GX, Ekrano GX) with a local display	`/opt/victronenergy/gui-v2/` on the GX device	For devices with attached touchscreens like GX Touch 50 or GX Touch 70
WebAssembly (WASM)	Runs in a web browser, hosted on the GX device or VRM server	`/var/www/venus/gui-v2/` on the GX device	Access the GUI remotely via a browser, with data fetched over MQTT
Desktop	Runs on a desktop (Linux, Windows, macOS)	Somewhere on your local computer	For development/testing purposes, it can get data over MQTT connection to a broker running on a GX device on the local LAN, or it can use a data simulator or mock mode

Build dependency version requirements

To build gui-v2 you need specific versions of Qt and emscripten. When building for device, you need a specific Venus OS SDK version, depending on the hardware type and firmware version of the GX device you are targeting.

Device build

You need to install an appropriate Venus OS SDK version, to target the (GX) device firmware version you are running on your device. For example, to target Venus OS v3.5X you should use an SDK like venus-dunfell-x86_64-arm-cortexa8hf-neon-toolchain-v3.50~YZ.sh, whereas to target Venus OS v3.6X you should use an SDK like venus-scarthgap-x86_64-arm-cortexa8hf-neon-toolchain-v3.60~YZ.sh, and to target Venus OS v3.7X you should use an SDK like venus-scarthgap-x86_64-arm-cortexa8hf-neon-toolchain-v3.70~YZ.sh.

Note that dunfell and scarthgap are Yocto release versions; currently scarthgap is used as the base for Venus OS, but in future this may change. To see if that is still being used, see here in the main Venus OS build script.

When using the SDK to build for device, there is no need to install Qt yourself, as the SDK will contain the right Qt version. See https://github.com/victronenergy/venus/blob/master/configs/scarthgap/repos.conf#L5 for the meta-qt6 version pulled into the Venus OS build.

If you build using the build scripts, installation of the latest SDK version will occur automatically.

WASM build & unit tests

See https://github.com/victronenergy/gui-v2/blob/main/scripts/.env for the Qt and Emscripten versions required to build the HEAD of the main branch of gui-v2.

If you use the build-wasm-install-requirements.sh scripts from the scripts folder then the correct versions are installed automatically.

Historical version requirements

Historical versions are listed for interest only. It may also be useful if special builds are required for historical versions for any reason. Note that the versions listed here show the step changes only. So, for example, every tagged version from v0.3.11 to v1.2.4 inclusive should be built with Qt 6.6.3 and emscripten 3.1.37.

gui-v2 v0.1.0 required Qt 6.2.4 and emscripten 2.0.14
gui-v2 v0.2.0 required Qt 6.5.2 and emscripten 3.1.25
gui-v2 v0.3.11 required Qt 6.6.3 and emscripten 3.1.37
gui-v2 v1.2.5 required Qt 6.8.3 and emscripten 3.1.56

Build options

There are various build options:

Building using the build scripts
Building manually

Building using the build scripts

In the repository you can find scripts that help you to install the requirements and build the GUI. To upload the new files, you need root access to your GX device.

Requirements to run the scripts

To use the build scripts located in the project scripts folder, ensure you have the following requirements met:

Ubuntu 24.x: Native support.
Windows: Use WSL to run the scripts in an Ubuntu environment.
macOS: Use Lima to create an Ubuntu container.

⚠️ NOTE: The build-wasm-install-requirements.sh script is currently not supported on macOS with ARM CPUs due to Qt licensing restrictions. This issue will be resolved with Qt version >= 6.7.0. For now, you can manually install the required dependencies.

Requirements to build the binaries

After opening an Ubuntu shell and navigating to the gui-v2 folder, install the required dependencies for the desired build type:

For GX device builds:

./scripts/build-gx-install-requirements.sh

For WebAssembly (WASM) builds:

./scripts/build-wasm-install-requirements.sh

💡 TIP: Re-run the appropriate script if the Venus OS version changes or if the Qt and/or emscripten versions are updated.

Building to run on a GX device

Run the following command in the gui-v2 directory:

Build only
```
./scripts/build-gx.sh
```
Build and automatically upload to one or more GX devices

It is possible to automatically upload the necessary files to one or more GX devices after building by using the -H or --host parameter. This parameter should be followed by a comma-separated list of hostnames and/or IP addresses. If you use this option, you can skip the manual deployment step (step 2).

When this option is used, the script performs the following steps:
- SSH Key Check: The script checks if an SSH key is already present on your system. If no SSH key is found, it will generate a new one.
- SSH Connection Test: The script attempts to connect to the GX device using the SSH key. If the connection fails, it will upload the SSH key to the GX device. During this step, you will need to enter the root password of the GX device once.
This process ensures that the necessary files are uploaded to the GX device automatically and securely, simplifying the deployment process.
```
./scripts/build-gx.sh -H <hostname-or-ip-of-gx-devices-separated-by-comma>
```
This creates a build-gx folder in the project root which contains all build files and a build-gx_files_to_copy folder containing all necessary files for the GX device.
Deploy the files to the GX device:
- Make the filesystem writable:
```
/opt/victronenergy/swupdate-scripts/remount-rw.sh
```
- Stop the running GUIv2 service:
```
svc -d /service/start-gui
```
- Copy the files to /opt/victronenergy/gui-v2 on the GX device, overwriting the existing files.
- Start the GUIv2 service:
```
svc -u /service/start-gui
```
If the GUI does not start or a page does not load, check the logs:
```
tail -F -n +1 /var/log/start-gui/current | tai64nlocal
```
Press CTRL + C to exit.

💡 TIP: If you are only changing QML files, you can directly change them on the GX device and restart the service, without the need to build the GUI again. It's still recommended to build and upload all the files at least once, to have the same base for the GX and WASM build.

Building to run in browser (WebAssembly/WASM)

Run the following command in the gui-v2 directory:

Build only
```
./scripts/build-wasm.sh
```
Build and automatically upload to one or more GX devices

It is possible to automatically upload the necessary files to one or more GX devices after building by using the -H or --host parameter. This parameter should be followed by a comma-separated list of hostnames and/or IP addresses. If you use this option, you can skip the manual deployment step (step 2 & step 3).

When this option is used, the script performs the following steps:
- SSH Key Check: The script checks if an SSH key is already present on your system. If no SSH key is found, it will generate a new one.
- SSH Connection Test: The script attempts to connect to the GX device using the SSH key. If the connection fails, it will upload the SSH key to the GX device. During this step, you will need to enter the root password of the GX device once.
This process ensures that the necessary files are uploaded to the GX device automatically and securely, simplifying the deployment process.
```
./scripts/build-wasm.sh -H <hostname-or-ip-of-gx-devices-separated-by-comma>
```
This creates a build-wasm folder in the project root which contains all build files and a build-wasm_files_to_copy folder containing all necessary files for the GX device.
Deploy the files to the GX device:
- Make the filesystem writable:
```
/opt/victronenergy/swupdate-scripts/remount-rw.sh
```
- Copy the files to /var/www/venus/gui-v2/ on the GX device, overwriting the existing files.
To see the changes via the VRM portal Remote Console, restart the vrmlogger service, and then wait for 5 minutes:
```
svc -t /service/vrmlogger
```
Alternatively, reboot the GX device, and then wait for 5 minutes.
If the GUI does not start or a page does not load, open the development tools of your browser and check the console.

Building manually

Building manually is not recommended, as you have to configure, patch, build, and install dependencies manually.

The information in this section easily becomes outdated as gui-v2 dependency versions change.

Building to run on a GX device

This section contains information on how to build gui-v2 as an ARM executable to run on a GX device.

Requirements

To build the gui-v2 for a GX device, ensure the following requirements are met:

Venus OS SDK:
- Your computer must have the Venus OS SDK installed.
- The SDK is only available for Linux hosts (bare metal, VM, or container) with an AMD/Intel (x86) processor.
- Note: Apple M2 processors are not supported for building.
- To install the SDK, follow the Venus OS SDK instructions.
- Use the most recent SDK to ensure compatibility with the Qt version used for building GUI-v2 and the GX device.
SSH Access:
- Ensure you have SSH access to the GX device. See root access instructions.
GX Device Firmware:
- The GX device must have a recent firmware version. Follow the instructions here to update the firmware.

Build

Once you have installed the SDK, you can use it to build gui-v2 for GX devices:

# source the sdk env (assuming it is installed or symlinked to /opt/venus/current/)
. /opt/venus/current/environment-setup-cortexa8hf-neon-ve-linux-gnueabi
# build gui-v2 and install to temporary directory
cd ~/gui-v2 # or wherever your code repository is
git checkout -b main origin/main
git submodule update --init
cd ..
mkdir -p build_gui-v2 && mkdir -p install_gui-v2
cd build_gui-v2
cmake -DCMAKE_BUILD_TYPE=MinSizeRel ../gui-v2/
cmake --build . --config MinSizeRel --parallel 1
cmake --install . --prefix ../install_gui-v2/
# tar up the installation
cd ../install_gui-v2/bin/
tar -czf install_gui-v2.tar.gz *

Before we can install to the device, we must stop the gui service on the GX, else some files are locked:

svc -d /service/start-gui
kill -9 `pidof venus-gui-v2`

Second, upload and extract the files:

scp ~/install_gui-v2/bin/install_gui-v2.tar.gz root@cerbogx:/opt/victronenergy/gui-v2/
ssh root@cerbogx
cd /opt/victronenergy/gui-v2/
tar -xzf install_gui-v2.tar.gz
chown -R root.root *

Alternatively, you can scp just the built executable (~/install_gui-v2/bin/venus-gui-v2) to the device to run it directly (but this will not transfer QML files to the device, so there are some edge-cases (e.g. load-from-filesystem mode) where this will not work as expected, so full installation of all artifacts is recommended instead):

scp ~/install_gui-v2/bin/venus-gui-v2 root@cerbogx:~/
ssh root@cerbogx
./venus-gui-v2

After installing the binary, you can start the gui service again:

svc -u /service/start-gui

Building to run in browser (WebAssembly/WASM)

This section contains information on how to build gui-v2 as a WASM executable to run within a web browser. There are four options:

Building for WebAssembly on Linux computer
Building for WebAssembly on Windows computer
Building for WebAssembly on Mac OS X computer
Building for WebAssembly via GitHub Actions (CI)

Finally, this chapter contains two sections explaining how to install it on the GX device as well as on VRM:

Patch and pack the WebAssembly files
Installing the WebAssembly artifacts to GX device

Note that the WASM blob will either be served directly by the CerboGX on local LAN, or by VRM over the internet. In the latter case, some specific semantics apply (for internal developers, see: https://github.com/victronenergy/venus-private/wiki/gui-v2-WASM-and-VRM) but should be seamless for clients.

Use the correct Qt and emscripten versions

Now and then we switch to newer versions of Qt (and the associated required version of emscripten), and updating this wiki page is easily forgotten. Hence, before doing all the installing and building of the toolchain, first check what versions we use at the moment by checking the versions used in our wasm ci workflow and/or the .env script.

Building for WebAssembly on Linux computer

This section contains information about how to build gui-v2 using a similar environment as is used to build official releases. The canonical build steps can be found in the GitHub Action script: build-wasm.yml.

These installation instructions are using aqt for installing Qt. Of course it is also possible to install all using the official Qt Maintenance Tool, but here aqt is used because it is more suitable for automated installs.

(If you want to use Qt installed via the Qt Maintenance Tool instead, first perform the steps described in the upcoming section "Install emscripten", and then ensure that you use the Qt Maintenance Tool to install Qt For WebAssembly, the Qt Shader Tools and Qt WebSockets modules, and the CMake developer tool, before proceeding to the upcoming section "Build and install QtMQTT". After that, you may proceed to "Build the wasm files".)

Installing dependencies

Starting with a recent (e.g. 24.04) Ubuntu Linux distribution:

sudo apt-get install -y g++ build-essential mesa-common-dev libssl-dev \
                        wget lsb libgl1-mesa-dev libxkbcommon-x11-0 libpulse-dev p7zip-full \
                        ninja-build dos2unix

As mentioned aqt is needed in order to follow the rest of the instructions:

pip install aqtinstall

The command yq is needed for running the later mentioned qt-fixes.sh script:

sudo snap install yq

Setting variables

Notice that the versions and install directory are set using environment variables. Make sure to source these first before copy/pasting the rest of the instructions. Check also the currently used versions here:

export EMSCRIPTEN=3.1.56
export QT_VERSION=6.8.3
export OUTPUTDIR=/opt/venus/build-gx-hostedtoolcache

Install Qt for desktop

aqt install-qt linux desktop ${QT_VERSION} gcc_64 -m qtwebsockets qt5compat qtshadertools --outputdir ${OUTPUTDIR}/Qt

This install is needed for building QtMQTT later on.

Install Qt for WebAssembly

aqt install-qt linux desktop ${QT_VERSION} wasm_singlethread -m qtwebsockets qt5compat qtshadertools --outputdir ${OUTPUTDIR}/Qt

Install Qt tools

aqt install-tool linux desktop tools_cmake --outputdir ${OUTPUTDIR}/Qt

Patching

If you've used the Qt Maintenance Tool for installation so far, this might not be needed. The aqt install however does miss some needed settings. It lacks some executable bits and has some paths wrong. On the Github Action side, the qt-fixes.sh shell script takes care of this. If you have used the same OUTPUTDIR (/opt/venus/build-gx-hostedtoolcache) and you have yq installed, you can run the script: ./.github/patches/qt-fixes.sh to do these patches for you. Otherwise please check that script and perform that patching manually.

Install emscripten

cd ${OUTPUTDIR}
git clone https://github.com/emscripten-core/emsdk.git
cd emsdk
./emsdk install ${EMSCRIPTEN}
./emsdk activate ${EMSCRIPTEN}

Build and install QtMQTT

cd ${OUTPUTDIR}
source "${OUTPUTDIR}/emsdk/emsdk_env.sh"
git clone https://github.com/qt/qtmqtt.git
cd qtmqtt
git checkout $QT_VERSION
mkdir build-qtmqtt && cd build-qtmqtt
export PATH=${OUTPUTDIR}/Qt/Tools/CMake/bin:$PATH
export QTDIR=${OUTPUTDIR}/Qt/$QT_VERSION/wasm_singlethread
${QTDIR}/bin/qt-configure-module ..
cmake --build .
cmake --install . --prefix ${QTDIR} --verbose

Build the wasm files

Finally, we are ready to actually build gui-v2 as a WASM executable (note that ${QTDIR} should have been exporting previously, see above):

git clone https://github.com/victronenergy/gui-v2.git
cd gui-v2
git submodule update --init
mkdir build-wasm
cd build-wasm
${QTDIR}/bin/qt-cmake -DCMAKE_BUILD_TYPE=MinSizeRel ..
cmake --build .

The build artifacts then need to be processed as per the "Patch and pack" instructions below before they can be installed to GX device.

Building for WebAssembly on Windows computer

First, install emscripten of the appropriate version (for Qt 6.8.3, emsdk install 3.1.56; emsdk activate 3.1.56). Second, install Qt For WebAssembly 6.8.3 via the Qt Maintenance Tool, and also include the Qt Shader Tools and Qt WebSockets modules. Then, build and install the QtMQTT module manually (as a binary build isn't offered in the Qt Maintenance Tool yet):

git clone https://github.com/qt/qtmqtt.git
cd qtmqtt
git checkout 6.8.3
mkdir build && cd build
CALL "C:\Program Files\Microsoft Visual Studio\2022\Community\VC\Auxiliary\Build\vcvarsall.bat" amd64
C:\Development\emscripten\emsdk\emsdk_env.bat
set PATH=C:\Development\Qt\Tools\CMake_64\bin;%PATH%
C:\Development\Qt\6.8.3\wasm_singlethread\bin\qt-configure-module.bat ..
C:\Development\Qt\Tools\CMake_64\bin\cmake.exe --build .
C:\Development\Qt\Tools\CMake_64\bin\cmake.exe --install . --verbose

Note that the vcvarsall.bat path may differ depending on which version of VS you have installed, e.g.: CALL "C:\Program Files\Microsoft Visual Studio\2022\Community\VC\Auxiliary\Build\vcvarsall.bat" amd64

Note for older Qt 6.6.3 builds:

Building qtmqtt 6.6.3 for wasm_singlethread on Windows 11 seems to have a couple of quirks.
First, need to edit ~/Qt/6.6.3/wasm_singlethread/lib/cmake/Qt6BuildInternals/QtBuildInternalsExtra.cmake to ensure that the Qt paths are properly escaped (e.g. C:\\Development\\Qt\\6.6.3\\wasm_singlethread instead of C:\Development\Qt\6.6.3\wasm_singlethread
Second, need to specify an install prefix manually (e.g. C:\Development\Qt\Tools\CMake_64\bin\cmake.exe --install . --prefix "C:\\Development\\Qt\\6.6.3\\wasm_singlethread" --verbose for the final step).
See https://github.com/victronenergy/gui-v2/issues/441#issuecomment-1681609453 for full instructions.

Once you have installed and built QtMQTT for Qt For WebAssembly, you can build gui-v2 as per normal using QtCreator.

The build artifacts then need to be processed as per the "Patch and pack" instructions below before they can be installed to GX device.

Testing the WebAssembly build from computer

The WebAssembly application needs to be served by a webserver.

The CerboGX has its own nginx HTTP server, and by default serves the content from /var/www/venus/gui-v2/ to the path http://<ip_address>/gui-v2/, which is why we install WebAssembly artifacts to GX device.

However, on desktop, you can serve it with emrun or another local webserver:

C:\Development\emscripten\emsdk\python\3.13.3_64bit\python.exe \
  C:/Development/emscripten/emsdk/upstream/emscripten/emrun.py \
    --browser chrome --port 30000 --no_emrun_detect
    --serve_after_close C:/build-wasm/artifacts/wasm/index.html

Note: any simple web server should suffice, if you don't have emrun.

Also note that the WebAssembly build will try to connect to the localhost by default. When serving the build from your host machine rather than the GX device, you will need to tell it to connect to a GX device on your network, by adding ?mqtt=ws://gx.device.ip.address:9001 to the url.

If you get an error like: module cgi not found after updating the version of emscripten you use to build gui-v2, this may be fixed by doing:

C:\Development\emscripten\emsdk\python\3.13.3_64bit\python.exe -m pip install legacy-cgi

Building for WebAssembly on Mac OS X computer

First, install emscripten of the appropriate version (for Qt 6.8.3, emsdk install 3.1.56; emsdk activate 3.1.56). Second, install Qt For WebAssembly 6.8.3 via the Qt Maintenance Tool, as well as the Qt Shader Tools and Qt WebSockets modules. Then, build and install the QtMQTT module manually (as a binary build isn't offered in the maintenance tool yet):

NOTE: when building for WebAssembly, run source /path/to/emsdk_env.sh before building to ensure that the emscripten toolchain is found, and use the qt-cmake and --prefix for Qt For WebAssembly (e.g. ~/Qt6/6.8.3/wasm_singlethread) instead of the desktop Qt.

# assumes Qt For WebAssembly 6.8.3 is installed under ~/Qt6/6.8.3/wasm_singlethread
cd ~/Qt6/
git clone https://github.com/qt/qtmqtt.git
cd qtmqtt
git checkout 6.8.3
cd ~/Qt6/
mkdir -p build-qtmqtt

# assumes you have installed emscripten to ~/emscripten/emsdk
source ~/emcripten/emsdk/emsdk_env.sh
cd ~/Qt6/build-qtmqtt
~/Qt6/6.8.3/wasm_singlethread/bin/qt-cmake ~/Qt6/qtmqtt
cmake --build .
cmake --install . --prefix ~/Qt6/6.8.3/wasm_singlethread --verbose

After building and installing the QtMqtt module as above, you can now build gui-v2 for WebAssembly, either using QtCreator, or via the following steps:

git clone https://github.com/victronenergy/gui-v2.git
cd gui-v2
git submodule update --init
mkdir build
cd build/
~/Qt6/6.8.3/wasm_singlethread/bin/qt-cmake -DCMAKE_BUILD_TYPE=MinSizeRel ../
/opt/Qt/Tools/CMake/bin/cmake --build .

The build artifacts then need to be processed as per the "Patch and pack" instructions below before they can be installed to GX device.

Building for WebAssembly via GitHub Actions

If you do not wish to set up a WebAssembly build environment on your own system, you may instead use GitHub Actions to build gui-v2.

To do this, trigger the GitHub action for gui-v2 (this will happen automatically for all branches and tags in the canonical gui-v2 repository) and once it completes it will become visible under the Actions list. You can click on the completed action to see its details, including its Artifacts (which should include a zip file which contains pre-patched and packed artifacts, ready for installation to the GX device).

To repeat: if building gui-v2 for WebAssembly via GitHub Actions, there is no need to perform the "Patch and pack" instructions below; you should instead proceed directly to the installation steps.

Patch and pack the WebAssembly files

Unless you use the CI system / GitHub Actions to build for WebAssembly, then regardless of which host you used to build the WebAssembly artifacts the important files need to be preprocessed before they are ready to be scp'd to the device.

The following script can be used for this purpose:

#!/bin/sh

# Run this after `cd ~/build-wasm/` directory
# (assumes gui-v2 repo is `~/gui-v2/` directory).
# Artifacts will be under ./artifacts/wasm
# ready for scp to device.

mkdir -p artifacts/wasm
cp venus-gui-v2.html venus-gui-v2.js venus-gui-v2.wasm qtloader.js victronenergy.svg victronenergy-light.svg mockup.svg artifacts/wasm/
cp -r ../gui-v2/wasm/icons artifacts/wasm/
mv artifacts/wasm/venus-gui-v2.html artifacts/wasm/index.html
grep -q -E '^var createQtAppInstance' artifacts/wasm/venus-gui-v2.js
sed -i "s%^var \(createQtAppInstance\)%window.\1%" artifacts/wasm/venus-gui-v2.js
grep -qxF "window.createQtAppInstance = venus_gui_v2_entry;" artifacts/wasm/venus-gui-v2.js || echo "window.createQtAppInstance = venus_gui_v2_entry;" >> artifacts/wasm/venus-gui-v2.js
cp ../gui-v2/.github/patches/Makefile artifacts/wasm/
cp ../gui-v2/LICENSE.txt artifacts/wasm/
cd artifacts/wasm/
stat -c%s venus-gui-v2.wasm > venus-gui-v2.wasm.size
gzip -k -9 venus-gui-v2.wasm
sha256sum venus-gui-v2.wasm > venus-gui-v2.wasm.sha256
rm venus-gui-v2.wasm

Note: the above script might get out of date; if unsure please check the (build-wasm.sh)[https://github.com/victronenergy/gui-v2/blob/main/scripts/build-wasm.sh] script for details of the up-to-date patch-and-pack requirements.

Installing the WebAssembly artifacts to GX device

Once the WebAssembly build artifacts are ready, they can be installed to the device:

cd ~/build-wasm/artifacts/wasm
make
scp * root@cerbogx:/var/www/venus/gui-v2/

Note: you might need to make the filesystem writable first, via running # /opt/victronenergy/swupdate-scripts/resize2fs.sh on device.

Now reboot the GX device (so that Nginx will serve the new content, and vrmlogger will inform VRM of the updated WASM blob), and wait 10 minutes. VRM should be notified of the change to the gui-v2 version, so that it can be launched from VRM. You may now launch gui-v2 either from your Local LAN (by browsing to https://gx.device.ip.address/gui-v2/) or from VRM (by clicking the Remote Console button when logged into the VRM website and viewing the relevant installation).

Building to run on desktop

This section contains information on how to build gui-v2 as a desktop executable on either Windows, Mac OS X, or Linux.

This is mostly for development/testing purposes, as desktop builds are NOT a supported target. It can be useful for developers as desktop builds still have access to the --mock backend, or unsecured MQTT broker backend via --mqtt gx.device.ip.address argument.

Building for Windows Desktop

First, install Qt 6.8.3 including Qt Shader Tools and also (from Additional Libraries) Qt WebSockets, using the Qt Maintenance Tool. Second, build and install QtMQTT manually:

git clone https://github.com/qt/qtmqtt.git
cd qtmqtt
git checkout 6.8.3
mkdir build && cd build
CALL "C:\Program Files\Microsoft Visual Studio\2022\Community\VC\Auxiliary\Build\vcvarsall.bat" amd64
C:\Development\Qt\6.8.3\msvc2022_64\bin\qt-configure-module.bat ..
C:\Development\Qt\Tools\CMake_64\bin\cmake.exe --build .
C:\Development\Qt\Tools\CMake_64\bin\cmake.exe --install . --verbose

Note: for debug builds, add --config Debug to the last two cmake commands.

Finally, you can build gui-v2 using QtCreator.

You can run gui-v2 with the --mock argument to test with the mock backend.

Building for Linux / Mac OS X Desktop

(This is what the Venus OS team members usually use: mac and linux.)

First, install Qt 6.8.3 including Qt Shader Tools and also (from Additional Libraries) Qt WebSockets, using the Qt Maintenance Tool. Second, build and install QtMQTT manually:

cd ~/Qt6/
git clone https://github.com/qt/qtmqtt.git
cd qtmqtt
git checkout 6.8.3
cd ~/Qt6/
mkdir -p build-qtmqtt
cd ~/Qt6/build-qtmqtt
~/Qt6/6.8.3/macos/bin/qt-cmake ~/Qt6/qtmqtt # or g++ instead of macos for linux builds
cmake --build .
cmake --install . --prefix ~/Qt6/6.8.3/macos --verbose  # or g++ instead of macos for linux builds

Finally, you can build gui-v2 using QtCreator, or via the following steps:

git clone https://github.com/victronenergy/gui-v2.git
cd gui-v2
git submodule update --init
mkdir build
cd build/
~/Qt6/6.8.2/macos/bin/qt-cmake -DCMAKE_BUILD_TYPE=MinSizeRel ../  # or g++ instead of macos for linux builds
cmake --build .

You can run gui-v2 with the --mock argument to test with the mock backend. (On Mac OS X, this is via: open bin/venus-gui-v2.app --args --mock.)

On Mac OS X, you may need to manually set the Qt6_DIR environment variable via export Qt6_DIR=/Users/username/Qt/6.8.3/macos/lib/cmake/Qt6/ if the above instructions do not work (typically: if you are using cmake from ~/Qt/Tools/CMake/bin rather than via the version-specific qt-cmake wrapper).

For troubleshooting, read these issues of others that went through this before you:

How to build venus gui v2

Build types

Build dependency version requirements

Device build

WASM build & unit tests

Historical version requirements

Build options

Building using the build scripts

Requirements to run the scripts

Requirements to build the binaries

Building to run on a GX device

Building to run in browser (WebAssembly/WASM)

Building manually

Building to run on a GX device

Requirements

Build

Building to run in browser (WebAssembly/WASM)

Use the correct Qt and emscripten versions

Building for WebAssembly on Linux computer

Installing dependencies

Setting variables

Install Qt for desktop

Install Qt for WebAssembly

Install Qt tools

Patching

Install emscripten

Build and install QtMQTT

Build the wasm files

Building for WebAssembly on Windows computer

Testing the WebAssembly build from computer

Building for WebAssembly on Mac OS X computer

Building for WebAssembly via GitHub Actions

Patch and pack the WebAssembly files

Installing the WebAssembly artifacts to GX device

Building to run on desktop

Building for Windows Desktop

Building for Linux / Mac OS X Desktop

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Clone this wiki locally