Neptune 3 UI - Run

To install all components of Qt Automotive Suite, see Installing Qt Automotive Suite. Once you have installed Qt Automotive Suite and launched Qt Creator, you can run your apps with Neptune 3 UI - on your desktop or on a target device, such as Intel NUC.

Alternatively, you can also build and run Qt Automotive Suite including Neptune 3 UI from the source code. This way you are able to modify any part of the code and experiment.

Run Neptune 3 UI using Qt Automotive Suite

See Installing Qt Automotive Suite to install all components of Qt Automotive Suite.

Neptune 3 UI depends on Qt Application Manager and Qt IVI. It provides support for both a Center Console display and an Instrument Cluster and uses the Qt IVI plugins to access various services. Neptune 3 UI offers a multi-process application model using a central System UI and various apps. The System UI provides an application launcher to start and stop apps. The Application Manager Plugin for Qt Creator allows a developer to develop and deploy apps using the Neptune 3 UI.

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

Run Neptune 3 UI using the Source Code

To explore Neptune 3 UI by building all components from the source code yourself, refer to the following instructions on how to run Neptune 3 UI on your desktop.


Neptune 3 UI is regularly tested on these platforms:

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

Multi-process UI and Single-process UI

Multi-process UI is the preferred mode. When in multi-process mode, apps run as independent processes, as Wayland clients. In this case, the System UI acts as a Wayland server, compositing the app windows in its own QML scene, as regular QML items.

In comparison with single-process mode, all app code run in the same QML scene and process as the System UI itself.


  • Qt 5.12 or higher
  • To support multi-process mode, your Qt installation must include the qtwayland submodule, and be built wiht Open GL ES (-opengl es2 -opengles3).


Build and Run Neptune 3 UI

  1. Clone the Qt Application Manager, the Qt IVI and the Neptune3-UI Git repositories.
  2. Build Qt Application Manager against Qt 5.12 or higher. See Qt Applicaton Manager Installation for more detailed build instructions.
  3. Build Qt IVI against Qt 5.12 or higher. See Qt IVI documentation for more detailed information.
  4. Build Neptune 3 UI by running the following command in a terminal:
  5. Run the following command in a terminal under the neptune3-ui installation directory:
    ./neptune3-ui -r --start-session-dbus

    Note: --start-session-dbus is required when you run Neptune 3 UI on Linux, in multi-process mode.

By default, Neptune style is used and am-config-neptune.yaml is the default configuration file. Hence, to load the LUCEE style for Neptune 3 UI, you must specify -c am-config-lucee.yaml when you start Neptune 3 UI.

Develop with Neptune 3 UI using Qt Creator

Once the project is cloned, built, installed, and all pre-requisites are configured, you can use QtCreator as your development tool. The following instructions describe how to build and run a project:

  • Start QtCreator and open the Neptune 3 UI project file.
  • Configure the project to use the Qt you have installed (see Adding Qt Versions).
  • Open your project's build steps configuration in Build > Build Settings > Build Steps (see Configuring Build Steps).
  • Expand the qmake Details and add an additional argument: INSTALL_PREFIX=/path/to/your/neptune/install/folder

    Note: This argument ensures that Neptune 3 UI is installed to the folder that you specify, instead of the default opt/neptune3/.

  • Expand the Make Details and add a make argument, such as -j8, depending on how many build jobs you want to use on your machine.
  • Open your project's run configuration in Run. In Run configuration, choose "neptune3-ui". You can also add other application manager options to the command line arguments, such as --recreate-database. See Application Manager Configuration for more information. Make sure that you run "neptune3-ui" from your install folder instead of your build folder.
  • Finally, build and run the project by selecting the Run button, or Ctrl + R.

Note: On Windows, when Neptune 3 UI is built and installed, a neptune3-ui_wrapper is generated to be able to find the required Qt libraries. Run this wrapper instead of the executable file.

Configure Neptune 3 UI

For maintainability, the UI configuration is split into several YAML files, as described in the following table:

am-config-neptune.yamlDefines the Center Console Display and Cluster-specific configurations. For example, built-in apps and their runtime (native or QML), import paths, UI-specific configurations (such as full-screen mode), and a main QML file (if it's a QML runtime). This YAML file configures Neptune 3 UI to use "neptune" style.
am-config-lucee.yamlSimilar to am-config-neptune.yaml, but this YAML file configures Neptune 3 UI to use "lucee" style.
info.yamlDefines an app-specific configuration, such as a main QML file and its imports.

The following code is an example of a am-config-neptune.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_shared/assets/icons" ]
  mainQml: "${CONFIG_PWD}/Main.qml"
  importPaths: [ "${CONFIG_PWD}/imports_shared", "${CONFIG_PWD}/imports_system", "${CONFIG_PWD}/sysui" ]
  windowIcon: "${CONFIG_PWD}/imports_shared/assets/icons/neptune/sysui/ic-menu-home.png"

    showCluster: yes
    showHUD: yes
    devMode: yes
    appStoreServerUrl: ''

# development setup: no security

  noSecurity: yes
  noUiWatchdog: yes

The YAML file contains options for system properties to show screens other than the Center Console, such as the Instrument Cluster or the HUD. These screens are enabled by default. Set showCluster or showHUD to no, to let Neptune 3 UI know that these screens should not be shown.

You can also set the devMode option to yes or no, to enable or disable Development Mode in Neptune 3 UI. When enabled, the Sheets app is included in the Application Launcher and developers acn see all of the components that Neptunen 3 UI supports, to develop an app.

All of 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: After you have changed the YAML files, you must regenerate the Yocto image for your target. See Building Embedded Linux Image for more details.

© 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.