Table of Contents

This documentation was created from git hash #e5921d3

User Guide

Introduction

Example Generic Vehicle Architecture HMI (Front Camera)

Execution

You can build vivoe-lite from source (See section on Building) or install from the pre build binaries on our website here.

Once installed the executable should be part of your PATH and can be ran from anywhere (/etc/profile.d/vivoe-lite.sh), if you have issues you can run with the full path:

$ /opt/gva/hmi-display

For help you can list the options using:

$ /opt/gva/hmi-display -h
hmi_display (By defencex.com.au)...rpm
 -h : help
 -w : Show HMI window, for debug when no GVA display present
 -v : Version
 -l : Live video
 -f : Fullscreen

For instructions in installing vivoe-lite binary packages please refer to the Developer SDK section.

Developer SDK Guide

This VIVOE (Vetronics Infrastructure for Video Over Ethernet) environment is currently tested on Ubuntu 22.04 LTS. Please ensure you have the following packages installed prior to building the application:

OS Specific setup

Ubuntu 22.04

$ sudo apt install libcairo2-dev libxt-dev libxml2-dev ncurses-dev libxext-dev libgflags-dev libswscale-dev libgtkmm-3.0-dev

And install these additional packages to build the documentation:

$ sudo apt install doxygen plantuml imagemagick

CentOS 8

On CentOS there are a few additional repos required for the software to build these are epel-release and powertools, below are the settings to set these prior to installing the dependencies

$ dnf install epel-release -y
$ dnf config-manager --set-enabled powertools -y
$ dnf localinstall --nogpgcheck https://download1.rpmfusion.org/free/el/rpmfusion-free-release-8.noarch.rpm -y
$ dnf update -y

Once the repos are updated install the following packages.

$ dnf install cmake gcc-c++ cairo-devel libXt-devel libxml2-devel ncurses-devel libXext-devel ffmpeg-libs protobuf-devel protobuf-compiler GeographicLib-devel gtk3-devel -y

And install these additional packages to build the documentation:

$ sudo dnf install doxygen plantuml ImageMagick

Windows 11

Cross compilation for Windows systems is achieved using MSYS2 (https://www.msys2.org/). Using the pacman package manager you can install all the required dependancies:

pacman -S base-devel \
  mingw-w64-x86_64-toolchain \
  mingw-w64-x86_64-gtk3 \
  mingw-w64-x86_64-gcc mingw-w64-x86_64-ffmpeg \
  mingw-w64-x86_64-nsis \
  mingw-w64-x86_64-doxygen \
  mingw-w64-x86_64-graphviz \
  mingw-w64-x86_64-imagemagick

To build the windows Nullsoft (https://nsis.sourceforge.io/) installer cpack from your build directory:

cpack -G NSIS

Building

This project has a couple of options that can be specified at compile time:

$ cmake -DCMAKE_BUILD_TYPE=Debug -DENABLE_COVERAGE=ON -DENABLE_OSMSCOUT=ON -DDDS=CYCLONE-CE ..

Default DDS stack is currently CycloneDDS (default if not specified) but can also be built with Opensplice by setting -DDDS=OSPL-CE.

To enable code coverage reports set ENABLE_COVERAGE. The gdb debugger is avaiable and configured for use with Microsoft Visual Code and the workspace files are part of the repo (recommended for developers).

The BMS function can be configured with Open Street Maps but these need to be compiled and installed onto the system. Its recommeded that you run wit these switched off if you do not need this functionality. See below for more information on creating maps for your region / territory.

Installing

Once the code is built the required files should be installed. There are two method for getting the files to their install locations. Firstly with cmake run:

$ sudo make install

Secondly you can create the platform specific install bundle and install that.

Ubuntu 22:04

$ cpack -G DEB

$ apt install vivoe-lite-cyclone-ce_<version>_amd64.deb -y

CentOS 8

$ cpack -G RPM

$ dnf install vivoe-lite-cyclone-ce-<version>>.x86_64.rpm -y

Developers

If you wish to start working with this code base then this section provides guidance for developers. The build system is CMake and you should have a good understanding of the CMake build system before station to add code into this reop.

The project to broken down into modules and submodules these can be seen in the diagram below:

CMake dependancies

Hardware

If you are usings the software control for screen brigtness then please ensure that the file /sys/class/backlight/intel_backlight/brightness is setup to control the backlight. Brightness functions will only work if the application is run with superuser permissions, if run as normal user then the brightness will not work and an error will be logged.

To manually set the brightness from the command line run:

$ echo 24000 > /sys/class/backlight/intel_backlight/brightness

Sets the brightness to 100%.

Tracing

To get a detailed view of whats going on in the code you can enable Linux Test Trace (See https://lttng.org/). This is enabled using the CMake macro shown below:

$ cmake -DTRACE=ON ..

Once built you can run with trace using the trace script in /scripts as shown below (from the build directory):

$ ../scripts/trace.sh ./bin/hmi-display

Trace files are now available in the defaullt location (normally $HOME) or in the directory poited to by $LTTNG_HOME/lttng-traces.

The recommeded GUI for viewing traces is trace compass by the Eclipse foundation. Tool can be downloaded here https://www.eclipse.org/tracecompass/

Import the trace and select the trace directory File -> Import. While importing select Create Experiment and set the log file type to Common Trace Format: LTTng UST Trace. At this point you can click ** Finish** to import.

Once imported you can open the experiment and view the interactive flame graph as shown below:

Flame Graph of code (Renderer section)

You may see raw addresses. To resolve the function names click and point to the binary executable:

Trace View resolve function names from binary file

Documentation

You can create this documentation on your own system using doxygen. It is recommended that you run the cmake target to handle the macro replacements for version information as shown below (in the build directory)

$ cmake ..

$ make doxygen

Images included in the documentation are autogenerated using the Widget Tester it is not recommended that youi run doxygen directly from the command line. If you do want to run doxygen directly then you will need to manuall specify the environment variables as shown below:

$ IMAGE_PATH=build/images/doxygen SEM_VERSION=<semantic_version> GIT_HASH=<hash> doxygen

To generate the images needed for doxygen then run the widget tester as sown below:

$ ./widget-tester -t 1

This will produce all the imagery needed for all the widgets currently supported. Images are .png files and contain transparency, these can be further cropped using the convert command below.

$ convert <image_dir>/*.png -trim +repage -set filename:f '%t' <output_dir>/doxygen/'%[filename:f].png

This needs to be done for every image. All handled in the make doxygen target.

Widgets

There are built in graphical elements that can be animated and extended to meet your requirements some of these are shown below.

Plan Position Indicator (PPI), Classic Tank

The PPI comes in servral modes, see gva::WidgetPlanPositionIndicator.

Classic tank PPI, Sight North

Classic tank PPI, Sight East

Classic tank PPI, Sight South

Classic tank PPI, Sight West

Classic tank PPI without Site

Classic tank PPI with threats overlay

Plan Position Indicator (PPI), Classic Arrow

Classic arrow PPI, Sight North

Classic arrow PPI, Sight East

Classic arrow PPI, Sight South

Classic arrow PPI, Sight West

Classic arrow PPI without Site

Classic arrow PPI with threats overlay

Plan Position Indicator (PPI), Modern

Modern PPI, Sight North

Modern PPI, Sight East

Modern PPI, Sight South

Modern PPI, Sight West

Modern PPI without Site

Modern PPI with threats overlay

On screen keyboard

The keyboard has servral input modes, see gva::WidgetKeyboard.

Keyboard, lower case

Keyboard, upper case

Keyboard, numeric case

Alarm indicator

The alarms states are displayed as follows, see gva::WidgetAlarmIndicator.

Advisory alarm example

Note the advisory state will take the current theme background.

Warning alarm example

Caution alarm example

Functional Areas (usually at the top of screen)

The functional area states are displayed as follows, see gva::WidgetTopLabels.

Function key states

Control Areas (usually at the bottom of screen)

The control states are displayed as follows, see gva::WidgetBottomLabels.

Control key states

Labels (usually at the side of screen, left and right)

The label states are displayed as follows, see gva::WidgetSideLabels.

Label key states

Operator Mode

A mode example can be seen below gva::WidgetMode. It is a GVA requirement that the operator is informed when the system is not operable due to maintinance.

Opertator mode

Tables

A table example example can be seen below gva::WidgetTable, add rows and cells as required these can be colour coded and highlighted for interactive table.

Table, example message box

Table, example alarms table

Drivers speedometer

The driver has some special widgets for operating the vehicle the speedometer gva::WidgetDriverSpeedometer is overlaid over the drivers camera.

Speed at 10 Km/h

Speed at 60 Km/h

Speed at 40 Mph

Drivers RPM and Fuel gauge

The driver has some special widgets for operating the vehicle the RPM and Fuel gauage gva::WidgetDriverRpmFuel is overlaid over the drivers camera.

RPM 0

RPM 4000

Special overlays for testing AI with object classification / loaclisation

This overlay is used with AI networks to highlight regions of interest.

Object Localisation

Tooling

Widget Tester

When creating new widgets it is advisable to add tests for the widget element. All widgets are derived from the gva::WidgetX base class. The simplest widget being the gva::WidgetMode which can be used as a basic example of how to create a new widget.

The test program widget-tester.cc can assist you in testing your new widget without needing to build the entire HMI. This tester is also used to autogenerate the imagry used in this documentation See Documentation

Widgets can then be rendered and viewed using the widget-tester.cc console program. The current widgets built into the SDK are shown below:

Diagram showing current widgets in the SDK

Open Street Map (OSM) file generation

To simplify the processing of maps for some countries a bash script is provided in the scripts/maps folder called scripts/maps/process_maps.sh. Currently three countries are processed with this script and these are:

England
Germany
Australia

Please feel free to modify the script to process the country/s you require. For convinience processed map archives are avaliable from the defencex.com.au website in the downloads area. These are updated on an adhock bases for testing purposes.

Once you have created your maps you will need to poit the config file at the map install location. Please edit and rebuild the config.proto file to point to you install location (osm.map_path).

Find you maps over on http://www.geofabrik.de/

OSMScout import guide https://libosmscout.sourceforge.net/tutorials/importing/

The default install locations for maps is under /opt below shows the sugested layout:

.
└── opt
   ├── gva
   │   ├── hmi
   │   │   └── images
   │   └── libs
   └── osmscout
      ├── maps
      │   ├── australia-latest 
      │   ├── england-latest 
      │   └── germany-latest 
      └── stylesheets
         └── include