Neptune 3 UI - Running

Typically, Neptune 3 UI works out-of-the-box after your have installed Qt Automotive Suite and launched Qt Creator. You can run your applications with Neptune 3 UI on your desktop or a target device.

The simplest way to experience Neptune 3 UI is using the Qt Automotive Suite. It is also possible to build and run the Qt Automotive Suite including Neptune 3 UI from source code being able to modify any part of the code and experiment any changes.

Running Neptune 3 UI using Qt Automotive Suite

Neptune 3 UI is part of Qt Automotive Suite. See Installing Qt Automotive Suite to install all components of Qt Automotive Suite. After Qt Automotive Suite have been installed, Neptune 3 UI can be run either on your desktop or your embedded devices, e.g. Intel NUC.

Neptune 3 UI depends on Qt Application Manager and Qt IVI. It provides support for a center stack display and an instrument cluster and uses the Qt IVI plugins to access various services. Neptune 3 UI offers a multiprocess application model using a central System UI and various applications. The System UI provides an application launcher to start and stop applications. The Application Manager Plugin for Qt Creator allows a developer to develop and deploy applications using the Neptune 3 UI.

Neptune 3 UI is distributed with the Qt Automotive Suite. Once the Neptune 3 UI component is selected and installed, the user can run the binary under your-qt-installation-path/qt-version/your-available-platform/neptune3, e.g. /home/qt/5.11.0/gcc-64/neptune3. If you use Qt Automotive Suite on an embedded device, the Neptune 3 UI binary will be located under /opt/neptune3/.

Running Neptune 3 UI using the source code

If you are interested in exploring Neptune 3 UI by building all components from the source code, follow these instructions to run Neptune 3 UI on your desktop:


Neptune 3 UI is tested regularly on these platforms:

  • macOS (single-process)
  • Linux desktop (single-process)
  • Linux desktop (multi-process)

Note: Multi-process UI (preferred): When in multi process mode, application run as independent processes, as wayland clients, and the System UI acts as a wayland server, compositing the application windows in its own QML scene, as regular QML items. While in single-process mode, all application code run in the same QML scene and process as the System UI itself.


  • Qt 5.11 or higher

Note: Qt installation need to include qtwayland submodule in order to support multi-process mode and built with Open GL ES (-opengl es2 -opengles3)


Build and run Neptune 3 UI

Development with Neptune 3 UI using Qt Creator

Once the project is cloned, built and installed and all pre-requisites are configured, you can use QtCreator as your development tool to open the project and do the development there. Follow these instructions to work with Neptune 3 UI using QtCreator:

  • Start QtCreator and open the Neptune 3 project file.
  • Configure the project to use your installed Qt (see Adding Qt Versions)
  • Open your project build steps configuration under Build Settings (under Projects → Build Settings → Build Steps) (see Configuring Build Steps)
  • Expand the qmake steps and add an install prefix to the additional arguments: e.g. INSTALL_PREFIX=/path/to/your/neptune/install/folder

    Note: this will install your Neptune 3 to the folder that you configured, otherwise by default, it will be installed under opt/neptune3/

  • Expand the build steps and insert an argument under make arguments: -j8 (depending on how many jobs you want to use in your machine)
  • Add another Build Step and choose "make" step. And insert the argument under make arguments: install -j8
  • Open your Run Settings and choose "neptune3-ui" under Run configuration. You can also have some other application manager options to be added into the Command line arguments, e.g. --recreate-database, etc. See this page for more information: Application Manager Configuration.
  • Finally you can build and run the project by pressing the Run button or press "Ctrl + R".

Configuring Neptune 3 UI

To improve the maintenance, the UI configuration is split into several .yaml files. The UI configuration files are listed and described in the following table:

am-config.yamlDefines the center stack display and cluster-specific configurations. For example, built-in applications and their runtime (native or QML), import paths, UI-specific configurations such as a full-screen mode and a main QML file (if runtime is QML).
info.yamlDefines an application-specific configuration. For example, a main QML file and its imports.

The following code defines an example of the am-config.yaml file:

formatVersion: 1
formatType: am-configuration

# basic AM functionality - the built-in apps are in 'apps'.
# installations will go into the standard /tmp/am hierarchy

  builtinAppsManifestDir: "apps"
  database: "/tmp/neptune3-ui/apps.db"

# QML apps will be able to import from modules...

    importPaths: [ "${CONFIG_PWD}/imports/shared" ]

# ... as well as the SystemUI

  fullscreen: yes
  style: "${CONFIG_PWD}/styles/neptune"
  iconThemeName: "neptune"
  iconThemeSearchPaths: [ "${CONFIG_PWD}/imports/assets/icons" ]
  mainQml: "${CONFIG_PWD}/Main.qml"
  importPaths: [ "${CONFIG_PWD}/imports/shared", "${CONFIG_PWD}/imports/system", "${CONFIG_PWD}/sysui" ]
  windowIcon: "${CONFIG_PWD}/imports/assets/icons/neptune/sysui/ic-menu-home.png"

    showCluster: yes
    devMode: yes
    appStoreServerUrl: ''

# development setup: no security

  noSecurity: yes
  noUiWatchdog: yes

These options are also configurable from the command line as a parameter to the appman utility. See Application Manager Configuration for more information.

appman --option 'ui: { fullscreen: no }'

Note: You must regenerate the Yocto image for your target after you have changed the yaml files. See Building Embedded Linux Image.

© 2018 Pelagicore AG. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.