1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
|
/****************************************************************************
**
** Copyright (C) 2019 Luxoft Sweden AB
** Contact: https://www.qt.io/licensing/
**
** This file is part of the Neptune 3 UI.
**
** $QT_BEGIN_LICENSE:FDL-QTAS$
** Commercial License Usage
** Licensees holding valid commercial Qt Automotive Suite licenses may use
** this file in accordance with the commercial license agreement provided
** with the Software or, alternatively, in accordance with the terms
** contained in a written agreement between you and The Qt Company. For
** licensing terms and conditions see https://www.qt.io/terms-conditions.
** For further information use the contact form at https://www.qt.io/contact-us.
**
** GNU Free Documentation License Usage
** Alternatively, this file may be used under the terms of the GNU Free
** Documentation License version 1.3 as published by the Free Software
** Foundation and appearing in the file included in the packaging of
** this file. Please review the following information to ensure
** the GNU Free Documentation License version 1.3 requirements
** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
** $QT_END_LICENSE$
**
****************************************************************************/
/*!
\page neptune3ui-qt-safe-renderer-integration.html
\title Neptune 3 UI - Qt Safe Renderer Integration
\brief The Qt Safe Renderer Integration in Neptune 3 UI
In Neptune 3 UI, \l{https://doc.qt.io/QtSafeRenderer/qtsr-overview.html}{Qt Safe Renderer} is
included in both:
\list
\li the regular UI part as QML components
\li the safety-critical UI part as a sample app, neptune3-ui-qsr-cluster
\endlist
The diagram below illustrates how these two integrations are done.
\image qt-safe-renderer-integration.png
\section1 Enable Qt Safe Renderer Support
To use Qt Safe Renderer on these \l{https://doc.qt.io/QtSafeRenderer/qtsr-supported-environment.html#supported-qt-versions-and-host-platforms}
{development environments}, build and install Qt Safe Renderer based on the steps described in
\l{Installing Qt Safe Renderer}.
Building Neptune 3 UI with Qt Safe Renderer available does the following:
\list
\li includes \c neptune3-ui-qsr-cluster to the build tree
\li enables the \l{Qt Safe Layout Tool} in the \c neptune3-ui.pro file, which generates
layout files into \c {BUILD_FOLDER/qsr-safelayout}, including a
\c {SafeTelltalesPanel.srl} file, that \c neptune3-ui-qsr-cluster uses
\endlist
\note If \c qmake doesn't find \e 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 \l{Neptune 3 UI - Middleware}{Middleware} provides the value sources
for Safe UI: telltales state, speed, and so on. The \c 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 \c neptune3-ui-qsr-cluster app expects to find both services
running at the same address. By default, it assumes the \c {tcp://127.0.0.1} 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 \c url property from the \c [lastUrls] group is used for the
connection.
\badcode
[lastUrls]
1\url=tcp://127.0.0.1:9999
2\url=tcp://192.168.0.1:1111
size=2
[ports]
remoteSettingsPort=9999
driveDataPort=9998
\endcode
These settings are based on \l{QSettings} with "Luxoft Sweden AB" as the company name and
"NeptuneCompanionApp" as the application name; to locate the file,
see \l{QSettings' Platform-Specific Notes}.
For the \c neptune3-ui-qsr-cluster and the \c 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 \l{Qt Safe Renderer QML plugin}. Qt Safe Renderer requires following environment
variables to be set for communication:
\badcode
QT_SAFERENDER_IPADDRESS=127.0.0.1
QT_SAFERENDER_PORT=1111
\endcode
They are set inside \c neptune3-ui using public system properties in the
\c {am-config-...} related files described in the following table:
\table
\header
\li Parameter Name
\li Type
\li Description
\row
\li qsrEnabled
\li bool
\li if set to \c yes, enables loading Safe telltales inside Cluster app (\c {SafeTellatales.qml}).
By default it is disabled.
\row
\li qsrServerAddress
\li string
\li The \c neptune3-ui-qsr-cluster server address
\row
\li qsrServerPort
\li string
\li The \c neptune3-ui-qsr-cluster server port
\endtable
The following is an example of Qt Safe Renderer settings in the {am-config-...} related files:
\badcode
systemProperties:
public:
qsrEnabled: yes
qsrServerAddress: '127.0.0.1'
qsrServerPort: '1111'
\endcode
For the \c neptune3-ui-qsr-cluster app, the TCP server's listening port is set in the
settings file based on \l{QSettings} with "Luxoft Sweden AB" as the company name and "QSRCluster"
as the application name; to locate the file, see \l{QSettings' Platform-Specific Notes}.
The default port is \c {1111}.
\badcode
[connection]
listen_port=1111
\endcode
\section1 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 \c OnFailure property. When \c neptune3-ui stops, the \c neptune3-ui-qsr-cluster app is
started by systemd.
The following code shows the "OnFailure" part of the \c {Neptune 3 UI}
service file, located in \c {/lib/systemd/system/neptune.service}:
\badcode
[Unit]
Conflicts=neptune-qsr.service
Before=neptune-qsr.service
OnFailure=neptune-qsr.service
\endcode
The \c {Safe UI} service file in \c {/lib/systemd/system/neptune-qsr.service} contains:
\badcode
[Service]
ExecStart=/opt/neptune3/neptune3-ui-qsr-cluster
workingDirectory=/opt/neptune3
Environment=QT_QPA_EGLFS_KMS_CONFIG=/etc/kms-qsr.conf
Environment=QSR_SHOW_TEXT_ON_STARTUP=1
Environment=QSR_FILL_BLACK_BACKGROUND=1
\endcode
The corresponding EGLFS settings JSON file (\c {/etc/kms-qsr.conf}) contains:
\badcode
{
"hwcursor": false,
"outputs": [
{
"name": "DP3",
"virtualIndex": 0,
"primary": true
}
]
}
\endcode
\section1 Safe UI App
\c 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
\l{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 \l{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:
\list
\li Loading layout generated from QML file inside Neptune 3 UI, which contains telltales images,
speed, power and warning texts
\li Interacting with Qt Safe Renderer library to render into buffer via the SafeWindow class
inherited from Qt Safe Renderer \l{AbstractWindow} and basic \l[QtGui]{QWindow}
\li Using the \l{StateManager} to control the UI elements' states
\li Communicating with \c {non-safe partition} via
\l{https://doc.qt.io/QtSafeRenderer/qml-qtsaferenderer-safemessage.html}{heartbeat messages}
and receiving notification that \c {Main UI} is about to shutdown. We use the simple Qt TCP
Server (\c TcpMsgHandler) for this.
\li Communicating with Neptune's \l {Neptune 3 UI - Middleware}
{Middleware} to get values of Safe UI elements states. The same \l{Qt IVI} auto
generated client is used as with Neptune's \l {Neptune 3 UI - Companion App}.
\endlist
\image qt-safe-renderer-error-cluster.png
The app's workflow is as follows:
\list
\li load generated layout from \c {BUILD_FOLDER/qsr-safelayout/SafeTelltalesPanel.srl}
\li create window and connect it to the Qt Safe Renderer \l{StateManager}
\li 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
\li start the \l{Neptune 3 UI - Middleware}{Middleware} Client to receive values for Safe UI
elements visibility states and text values
\endlist
\section1 Run on Desktop
\image qt-safe-renderer-overlay.png
To run Qt Safe Renderer on desktop, first start \c neptune3-ui and then run
\c neptune3-ui-qsr-cluster app. The transparent Safe UI window is shown with the same telltales,
text values for speed and power as Neptune 3 UI cluster shows.On desktop, it's possible to
place a Qt Safe Renderer window directly over Neptune 3 UI's cluster window to demonstrate that
telltales are positioned and scaled the same on both Safe and Non-Safe parts. Cluster window
positions are sent from the non-safe partition to the Safe part if Qt Safe Renderer support is
enabled. For \c neptune3-ui-qsr-cluster overlaying of Neptune's 3 UI Cluster window is enabled
by default and can be switched off by modifying the Boolean key in the settings file based on
\l{QSettings' Platform-Specific Notes}{QSettings} with "Luxoft Sweden AB" as the company name and
"QSRCluster" as the application name:
\badcode
[gui]
stick_to_cluster=false
\endcode
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
\l{https://doc.qt.io/QtSafeRenderer/qtsr-functionalities.html#rendering-safety-critical-and-non-safe-ui}
{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.
\section1 Specific Options for Target Device
Running the \c 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 \c QSR_FILL_BLACK_BACKGROUND environment variable to \c 1.
When the \c neptune3-ui-qsr-cluster app can't access the keep-alive messages, and it started
after the \c{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
\c QSR_SHOW_TEXT_ON_STARTUP environment variable to \c 1.
*/
|