Neptune 3 UI - Qt Safe Renderer Integration

In Neptune 3 UI, Qt Safe Renderer is included in both:

  • the regular UI part as QML components
  • the safety-critical UI part as a sample app, neptune3-ui-qsr-cluster

The diagram below illustrates how these two integrations are done.

Enable Qt Safe Renderer Support

To use Qt Safe Renderer on these development environments, build and install Qt Safe Renderer based on the steps described in Installing Qt Safe Renderer.

Building Neptune 3 UI with Qt Safe Renderer available does the following:

  • includes neptune3-ui-qsr-cluster to the build tree
  • enables the Qt Safe Layout Tool in the file, which generates layout files into BUILD_FOLDER/qsr-safelayout, including a file, that neptune3-ui-qsr-cluster uses

Note: If qmake doesn't find qtsaferenderer installed, the following warning message is shown at build step: "The qtsaferenderer module is not available: Make sure that QtSafeRenderer is installed and configured correctly"

The Client to Neptune's Middleware provides the value sources for Safe UI: telltales state, speed, and so on. The neptune3-ui-qsr-cluster app connects to the same remote middleware services and utilizes the same autogenerated QtIVI interfaces and mechanisms as Neptune 3 UI. The neptune3-ui-qsr-cluster app expects to find both services running at the same address. By default, it assumes the tcp:// address, ports 9998 for the drivedata-simulation-server and 9999 for the remotesettings-server. To override these default parameters, modify the app's settings file to add values for the address and ports as shown below. The first url property from the [lastUrls] group is used for the connection.


These settings are based on QSettings with "Luxoft Sweden AB" as the company name and "NeptuneCompanionApp" as the application name; to locate the file, see QSettings' Platform-Specific Notes.

For the neptune3-ui-qsr-cluster and the neptune3-ui apps to communicate, we use a TCP connection. TCP client is on non-safe partition and server is on Safe UI part. TCP client is a part of the Qt Safe Renderer QML plugin. Qt Safe Renderer requires following environment variables to be set for communication:


They are set inside neptune3-ui using public system properties in the am-config-... related files described in the following table:

Parameter NameTypeDescription
qsrEnabledboolif set to yes, enables loading Safe telltales inside Cluster app (SafeTellatales.qml). By default it is disabled.
qsrServerAddressstringThe neptune3-ui-qsr-cluster server address
qsrServerPortstringThe neptune3-ui-qsr-cluster server port

The following is an example of Qt Safe Renderer settings in the {am-config-...} related files:

        qsrEnabled: yes
        qsrServerAddress: ''
        qsrServerPort: '1111'

For the neptune3-ui-qsr-cluster app, the TCP server's listening port is set in the settings file based on QSettings with "Luxoft Sweden AB" as the company name and "QSRCluster" as the application name; to locate the file, see QSettings' Platform-Specific Notes. The default port is 1111.


Non-safe to Safe UI Switching on the NUC Target

On the NUC target you can switch between Non-Safe and Safe UI via systemd service monitoring using OnFailure property. When neptune3-ui stops, the neptune3-ui-qsr-cluster app is started by systemd.

The following code shows the "OnFailure" part of the Neptune 3 UI service file, located in /lib/systemd/system/neptune.service:


The Safe UI service file in /lib/systemd/system/neptune-qsr.service contains:


The corresponding EGLFS settings JSON file (/etc/kms-qsr.conf) contains:

    "hwcursor": false,
    "outputs": [
            "name": "DP3",
            "virtualIndex": 0,
            "primary": true

Safe UI App

neptune3-ui-qsr-cluster is a sample "Safe UI part" implementation of Qt Safe Renderer inside Neptune 3 UI project. It is based on the desktop part of Qt Safe Renderer Example Telltales: Rendering Safety-Critical UI, that illustrates how to develop with Qt Safe Renderer in a desktop environment.

Note: This sample is not implemented according to Misra C++ 2008 nor ISO26262 functional safety standards as the sample depends on Qt classes.

In this sample main aspects of work with Qt Safe Renderer are presented:

  • Loading layout generated from QML file inside Neptune 3 UI, which contains telltales images, speed, power and warning texts
  • Interacting with Qt Safe Renderer library to render into buffer via the SafeWindow class inherited from Qt Safe Renderer AbstractWindow and basic QWindow
  • Using the StateManager to control the UI elements' states
  • Communicating with non-safe partition via heartbeat messages and receiving notification that Main UI is about to shutdown. We use the simple Qt TCP Server (TcpMsgHandler) for this.
  • Communicating with Neptune's Middleware to get values of Safe UI elements states. The same Qt IVI auto generated client is used as with Neptune's Neptune 3 UI - Companion App.

The app's workflow is as follows:

  • load generated layout from BUILD_FOLDER/qsr-safelayout/
  • create window and connect it to the Qt Safe Renderer StateManager
  • start the TCP server to process heartbeats from non-safe partition and show a warning if a timeout or shutdown signal is emitted; hide them on new heartbeats
  • start the Middleware Client to receive values for Safe UI elements visibility states and text values

Run on Desktop

To run Qt Safe Renderer on desktop, first start middleware services: remotesettings-server and drivedata-simulation-server.

Note: If these services are not started before Neptune 3 UI app, they will be stopped after the app has been closed.

Then start neptune3-ui and afterwards neptune3-ui-qsr-cluster app. The transparent Safe UI window is shown with the same telltales and text values for speed and power as in Neptune 3 UI cluster. It's possible to place a Qt Safe Renderer window directly over Neptune 3 UI's cluster window in the desktop version to demonstrate that telltales have the same position and scale on both Safe and Non-Safe parts. If Qt Safe Renderer support is enabled, cluster window positions are sent from the non-safe partition to the safe part. For neptune3-ui-qsr-cluster Neptune 3 UI Cluster window overlay is enabled by default and can be switched off by modifying the Boolean key in the settings file based on QSettings with "Luxoft Sweden AB" as the company name and "QSRCluster" as the application name:


This key is used to demonstrate how the whole cluster looks: Neptune 3 UI at the bottom and safe elements on top as if the cluster was rendered on an actual target with hardware layering. On desktop, however, there's no hardware layering, so we manually place one window on top of another. We also make that window "follow" the coordinates of the other to synchronize their positions on the screen.

Specific Options for Target Device

Running the neptune3-ui-qsr-cluster app on a target device, such as an Intel NUC, may require the application window to have an opaque background. To enable the app to fill this background automatically, set the QSR_FILL_BLACK_BACKGROUND environment variable to 1.

When the neptune3-ui-qsr-cluster app can't access the keep-alive messages, and it started after the Main UI application was stopped or crashed, you may need to display the warning message, speed values and power, on startup. To enable this, set the QSR_SHOW_TEXT_ON_STARTUP environment variable to 1.

© 2019 Luxoft Sweden AB. 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.