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
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
|
/****************************************************************************
**
** Copyright (C) 2019 Luxoft Sweden AB
** Contact: https://www.qt.io/licensing/
**
** This file is part of the documentation of the QtIvi module of the Qt Toolkit.
**
** $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$
**
****************************************************************************/
/*!
\example ivicore/qface-tutorial
\brief Demonstrates step-by-step how to generate a Middleware API based on a QML application.
\ingroup qtivicore-examples
\title Qt IVI Generator Tutorial
\image examples_qface_tutorial.png
This tutorial demonstrates how you can extend a QML application with your own autogenerated
Middleware API. We use an existing QML Instrument Cluster application and proceed through the
following steps:
\list 1
\li \l{chapter1}{Integrate a basic interface without a backend}
\li \l{chapter2}{Extend the interface and add annotations}
\li \l{chapter3}{Add a simulation backend and corresponding simulation annotations; with a QML plugin}
\li \l{chapter4}{Add a custom simulation behavior}
\li \l{chapter5}{Add a simulation server and use it from a Qt Remote Objects Backend}
\li \l{chapter6}{Develop a production backend that connects to a DBus interface}
\endlist
Before we start the actual Middleware integration, let's take a look at the existing Instrument
Cluster QML code and all the features it supports:
\list
\li \c images -- This folder contains all images used in the QML code.
\li \c Cluster.qml -- The main QML file that assembles all other QML components together.
\li \c Dial.qml -- The base component to show values like speed or Revolutions per Minute
(RPM), using a needle.
\li \c Fuel.qml -- The component to show the actual fuel level.
\li \c Label.qml -- A small helper component which sets all common settings used to display
text.
\li \c LeftDial.qml -- Shows the current speed using the Dial component and as text, as
well as the current metric in miles per hour (mph) or kilometers per hour (km/h).
\li \c RightDial.qml -- Shows the current RPM and offers a way to show warning indicators.
\li \c Top.qml -- The top bar that shows the current date and the current temperature.
\endlist
Next, we use our Middleware API to add support for the following features:
\list
\li Show the current speed in the left dial.
\li Show the current RPM in the right dial.
\li Change between different metrics.
\li Show the current temperature in the top bar.
\li Show different warnings on the right dial.
\li Indicate whether the instrument cluster is connected and show real data.
\endlist
The ultimate goal is to connect all of these features together to simulate a real-time driving
experience like this:
\image examples_qface_tutorial_final.gif
\target chapter1
\section1 Chapter 1: Basic Middlware API with the IVI Generator
In this chapter we integrate a Middleware API into the existing Instrument Cluster QML code.
Instead of manually writing all of these parts ourselves, which is done in most basic
\l{https://doc.qt.io/qt-5/qtquick-codesamples.html}{QML examples}, we'll use the IVI Generator
to autogenerate the required parts.
\target define-speed-property
\section2 Interface Definition Language
To be able to autogenerate the Middleware API, the IVI Generator needs some input on what to
generate. This input is given in form of an Interface Definition Language (IDL), QFace, which
describes the API in a very simple way.
Let's start to define a very simple interface which provides us with a speed property:
\quotefromfile ivicore/qface-tutorial/chapter1-basics/instrument-cluster.qface
\printuntil }
First, we need to define which module we want to describe. The module acts as a namespace,
because the IDL file can contain multiple interfaces.
\quotefromfile ivicore/qface-tutorial/chapter1-basics/instrument-cluster.qface
\printuntil module
The most important part of the module is its interface definition.
\quotefromfile ivicore/qface-tutorial/chapter1-basics/instrument-cluster.qface
\skipto interface
\printuntil }
In this case, we define an interface named \c InstrumentCluster that consists of one property.
Each property definition must contain at least a type and a name. Most of the basic types are
built-in and can be found in the \l{QFace IDL Syntax}.
\section2 Autogeneration
Now that our first version of the IDL file is ready, it's time to autogenerate API from it,
using the \l{Qt IVI Generator}{IVI Generator tool}. Similar to
\l{https://doc.qt.io/qt-5/moc.html}{moc}, this autogeneration process is integrated into the
qmake Build System and is done on compile time.
In the following \c{.pro} file we build a C++ library based on our IDL file:
\quotefromfile ivicore/qface-tutorial/chapter1-basics/frontend/frontend.pro
\printto CONFIG += install_ok
Most of the \c{.pro} file is a standard setup to define a C++ library, using "lib" \c TEMPLATE
and defining the required file name in the \c TARGET variable. The \c qtLibraryTarget function
that we use helps to append the "d" postfix on the filename correctly, for a library that
provides debugging information. In the future, we need to link this file, so we set the
\c DESTDIR to the upper directory to simplify this.
\note Windows searches for libraries in the same directory automatically.
Activating the IVI Generator integration requires the \c CONFIG variable to specify the
\c ivigenerator option. This makes sure the IVI Generator is called during the build process,
using the QFace file that we specify in \c QFACE_SOURCES. For more information, see
\l{qmake integration}.
To make sure the library we build works on Windows, it's important to add the
\c QT_BUILD_EXAMPLE_IVI_INSTRUMENTCLUSTER_LIB to the \c DEFINES variable. This way, all symbols
are exported when building the library, but imported when linking against it. For more
information, see \l{https://doc.qt.io/qt-5/sharedlibrary.html}{Creating Shared Libraries}.
\section2 Which Files are Autogenerated
The IVI Generator works based on generation templates. These templates define what content
should be generated from a QFace file. If no \c QFACE_FORMAT is defined, this automatically
defaults to "frontend" template. For more details on these templates, see \l{Use the Generator}.
In short, the "frontend" template generates:
\list
\li a C++ class derived from QIviAbstractFeature for every interface in the QFace file
\li one module class that helps to register all interfaces to QML and stores global types
and functions.
\endlist
To inspect the C++ code yourself, you can view these files in the your library's build folder.
Right now, the most important autogenerated file for us, is the resulting C++ class for our
defined interface. It looks like this:
\quotefile ivicore/qface-tutorial/chapter1-basics/frontend/instrumentcluster.h
As you can see, the autogenerated C++ class implements a \c speed property, that we previously
defined in the QFace file. By using the \c Q_OBJECT and \c Q_PROPERTY macros, the class is now
ready for use directly in your QML code.
\section2 Integrate the Frontend Library with the QML Code
For this integration, we use the autogenerated frontend library from the QML code. For the sake
of simplicity, we follow the standard Qt example pattern and use a small C++ main function
which registers our autogenerated types to QML and loads the Instrument Cluster QML code into
the QQmlApplicationEngine:
\quotefromfile ivicore/qface-tutorial/chapter1-basics/instrument-cluster/main.cpp
\skipto #include "instrumentclustermodule.h"
\printuntil }
All we need now is the actual integration of the InstrumentCluster QML element and connecting
the \c speed property to the \c leftDial. This is done by instantiating the element first with
the \c instrumentCluster ID.
\quotefromfile ivicore/qface-tutorial/chapter1-basics/instrument-cluster/Cluster.qml
\skipto import
\printuntil InstrumentCluster
\printuntil }
\codeline
Lastly, we can create a Binding for the \c LeftDial Item's \c value property to our
InstrumentCluster API's \c speed property.
\printuntil }
\target chapter2
\section1 Chapter 2: Extend the Interface and add Annotations
In this chapter we extend our Middleware API with more properties via enums and by defining our
own structure.
\section2 Define Speed as a Read-only Property
\l{define-speed-property}{Previously}, we defined the speed property in our QFace file in the
following way:
\quotefromfile ivicore/qface-tutorial/chapter1-basics/instrument-cluster.qface
\printuntil }
This property is defined as readable and writable, as we didn't use any extra specifiers.
However, it's not necessary for our Instrument Cluster example to have a writable \c speed
property because it's not used to accelerate the car, but just to visualize the current state.
To define the property as read-only, use the \c readonly keyword.
\quotefromfile ivicore/qface-tutorial/chapter2-enums-structs/instrument-cluster.qface
\printuntil readonly
\skipto }
\printuntil }
When we build our app again, the build system recognizes this change and runs the IVI
Generator to generate an updated version of the C++ code. After the IVI Generator is done,
open the \c instrumentcluster.h from the build folder and notice that the generated
\c speed property changed -- it no longer has a setter anymore and is now read-only.
\quotefromfile ivicore/qface-tutorial/chapter2-enums-structs/frontend/instrumentcluster.h
\skipto class Q_EXAMPLE
\printuntil Q_PROPERTY
\dots
\skipto };
\printuntil };
\section2 Extend the Interface
To reach our goal to provide a full simulation for the Instrument Cluster, we need to add more
properties to our QFace file: \c rpm, \c fuel and \c temperature:
\quotefromfile ivicore/qface-tutorial/chapter2-enums-structs/instrument-cluster.qface
\printuntil readonly real temperature
\skipto }
\printuntil }
You might have noticed that we use a different type for the \c fuel and \c temperature
properties. We use \c real here, as we would like to show the temperature as a floating point
number, and the current fuel level as a value between 0 and 1.
\section2 Define a New Enum Type
One useful feature is to be able to switch between the metric and the imperial system, so we
need to define a property for the system we currently use. Using a boolean property would work,
but doesn't offer a nice API, so we define a new enum type in the QFace file and use it as the
type for our new \c system property:
\quotefromfile ivicore/qface-tutorial/chapter2-enums-structs/instrument-cluster.qface
\printuntil readonly SystemType
\skipto }
\printuntil enum
\printuntil }
In the autogenerated code, this results in an enum which is part of the module class, making it
possible for the same enum to be used by multiple classes which are part of the same module:
\quotefile ivicore/qface-tutorial/chapter2-enums-structs/frontend/instrumentclustermodule.h
\section2 Add a New Structure
To display warnings on the Instrument Cluster's right dial, we'd like to use a structure that
stores color, icon, and text for the warning; instead of using 3 independent properties.
Similar to defining an interface, we can use the \c struct keyword in our QFace file:
\quotefromfile ivicore/qface-tutorial/chapter2-enums-structs/instrument-cluster.qface
\skipto struct
\printuntil }
Using this new structure as a type for a property, works in the same way as when using an enum.
The QFace file should now look like this:
\quotefile ivicore/qface-tutorial/chapter2-enums-structs/instrument-cluster.qface
\section2 Integrate the New Properties
Like in the previous chapter, actually integrating the newly introduced properties involves
creating Bindings. The \c rpm property can be directly connected to the \c rightDial Item's
\c value property; the same is done for the top Item's \c temperature property. To control
which unit is displayed in the left Dial, the \c leftDial Item provides \c metricSystem, a bool
property. As we used an enum in our QFace file, we need to convert the value first by testing
the \c sytemType property for the "Metric" value.
\quotefromfile ivicore/qface-tutorial/chapter2-enums-structs/instrument-cluster/Cluster.qml
\skipto LeftDial
\printuntil }
\codeline
These enums are part of the module class, which is also exported to QML as
\c InstrumentClusterModule. To trigger a warning in the \c rightDial Item, we use 3 bindings to
connect to the 3 member variables in the structure:
\printuntil }
\target chapter3
\section1 Chapter 3: Add a Simulation Backend and Annotations with a QML plugin
In the previous two chapters, we wrote a Middleware API using a QFace file and used the IVI
Generator to autogenerate a C++ API in the form of a library. Now, in this chapter, we extend
this further by introducing a simulation backend and using annotations to define default values
for our simulation.
\section2 Separation between the Frontend and Backend
Both QtIvi and the IVI Generator enable you to write code that separates the frontend from the
backend -- to split an API from its actual implementation. Already, Qt uses this concept in a
lot of areas, most prominently in the underlying window system technology on various Qt
platforms like XCB on Linux and Cocoa on macOS.
The same separation is done for our Middleware API, where the frontend provides the API as
a library; the backend provides an implementation of this API. This implementation is based on
QtIvi's \l{Dynamic Backend System} which enables us to switch between such backends at runtime.
\image feature-backend.png
\section2 Add a Simulation Backend
For our Instrument Cluster, we'd like to add such a backend to provide actual values. For now,
we'd like to just have some simulation behavior as we can't connect it easily to a real car.
This is why such backends are called "simulation backend". To add this type of backend, once
again, we use the IVI Generator to do the heavy lifting for us and generate one. This work
is done in a similar way to when we generated a library with the "frontend" template. But now,
we are using the "backend_simulator" template:
\quotefromfile ivicore/qface-tutorial/chapter3-simulation-backend/backend_simulator/backend_simulator.pro
\printto DESTDIR
\skipto QT
\printuntil CONFIG
\skipto QFACE_FORMAT
\printto CONFIG += install_ok
Just like for the frontend library, the project file builds a \c lib and defines the library
name using \c qtLibraryTarget to also support the Windows debug postfix. One important aspect
here is that the library name ends with "_simulation", which is a way to tell QtIvi that this
is a simulation backend. When a "production" backend is available, it is preferred over the
"simulation" one. For more information, see \l{Dynamic Backend System}.
Enabling the IVI Generator is also done in the same way as we did earlier: by using the same
\c QFACE_SOURCE variable, but defining \c QFACE_FORMAT to "backend_simulator", to use the
correct generation template. In addition, we need to add 'plugin' to the \c CONFIG variable,
to make this library a Qt plugin which can be easily loaded at runtime.
\section2 Link Settings and Locating Plugins
Trying to build the project file just as it is, right now, would result in compilation and
linking errors. This is because: to do the frontend and backend separation, we need to have the
backend implement a defined interface class, that is known to the frontend. This interface is
aptly called "backend interface" and is automatically generated as part of the frontend
library. Because this class provides signals and slots and uses QObject for its base class, you
need to link to the frontend library when you inherit from it. As this is needed for the
backend plugin, we need to add the following lines in addition:
\quotefromfile ivicore/qface-tutorial/chapter3-simulation-backend/backend_simulator/backend_simulator.pro
\skipuntil CONFIG
\printuntil INCLUDEPATH
Now the project should build fine and create the plugin in your build folder; or the plugin
folder if you don't use a shadow build. When you start the Instrument Cluster again, you should
see the following message:
\badcode
There is no production backend implementing "Example.IVI.InstrumentCluster.InstrumentCluster" .
There is no simulation backend implementing "Example.IVI.InstrumentCluster.InstrumentCluster" .
No suitable ServiceObject found.
\endcode
This message indicates that QtIvi is still unable to find the simulation plugin we just created.
Here, you need to know a little bit more about Qt's Plugin System, especially how it it finds
plugins.
Qt searches for it's plugins in multiple directories, the first one is the plugin folder,
\c plugins, which comes with your Qt installation. Within the plugins folder, every plugin type
has it's own sub-folder, such as \c platforms, for the platform plugins used to talk to the
underlying platform API and the windowing system.
Similarly, QtIvi searches for its backend plugins in the \c qtivi folder. To make sure our
simulation backend ends up in such a folder, we add the following \c DESTDIR definition.
\quotefromfile ivicore/qface-tutorial/chapter3-simulation-backend/backend_simulator/backend_simulator.pro
\skipto DESTDIR
\printuntil DESTDIR
You might wonder how creating a \c qtivi folder in the upper directory solves this problem of
finding the plugin as it's not part of the system plugins folder. But Qt supports searching in
multiple folders for such plugins and one of those folders is the path to where the executable
itself is located.
Alternatively, we could add an additional plugin path using the QCoreApplication::addLibraryPath()
function or using the \c QT_PLUGIN_PATH environment variable. For more information, see
\l{https://doc.qt.io/qt-5/plugins-howto.html}{How to create Qt Plugins}.
Now everything is in place, but because our plugin links against the frontend library, we need
to make sure the library can be found by the dynamic linker. This can be achieved by
setting the \c LD_LIBRARY_PATH environment variable to our library folder. But this results
in the problem, that every user would need to set this variable to be able to use our
application.
To make things easier for the user, we rather use a relative RPATH instead and annotate our
plugin with the information for the linker, where it might find the needed libraries, relative
to the plugin's location:
\quotefromfile ivicore/qface-tutorial/chapter3-simulation-backend/backend_simulator/backend_simulator.pro
\skipto INCLUDEPATH
\printuntil QMAKE_RPATHDIR
\section2 Export the QML Types in a QML Plugin
In the first chapter, we extended our \c main.cpp to register all types of our autogenerated
Middleware APIs. Although this works fine, in bigger projects it's common to use a QML Plugin
instead and be able to use qmlscene for development. Although the code for doing this is
not complex, the IVI Generator supports this as well and makes it even easier.
From the first chapter, we know that the module name is used for the QML import URI. This is
important for a QML plugin as the QmlEngine expects the plugin in a specific folder to
follow the module name, where every section of the module name is a sub-folder. Our project
file to generate a QML plugin looks like this:
\quotefromfile ivicore/qface-tutorial/chapter3-simulation-backend/imports/imports.pro
\printto target.path
All lines until \c QFACE_SOURCES should be familiar. We use \c CONFIG to build a plugin, then
define the settings for the linker to link against our frontend library. Then, we use
\c QFACE_FORMAT to define "qmlplugin" as the generation template. Instead of adding
\c ivigenerator to \c CONFIG, this time we use
\l{https://doc.qt.io/qt-5/qmake-test-function-reference.html#load-feature}
{qmake's load() function} to explicitly load the feature. This enables us to use the \c URI
variable which is part of the "qmlplugin" generation template. This URI can be used to define
a \c DESTDIR by replacing all dots with slashes.
In addition to the folder structure, the QmlEngine also needs a \c qmldir file which indicates
what files are part of the plugin, and under which URI. For more information, see
\l{https://doc.qt.io/qt-5/qtqml-modules-qmldir.html}{Module Definition qmldir Files}. Both this
\c qmldir file and a \c plugins.qmltypes file which provides information about code-completion,
are autogenerated by the IVI Generator; but they need to be placed next to the library. To do
so, we add the files to a scope similar to an \c INSTALL target, but add it to the \c COPIES
variable instead. This makes sure that the files are copied when the plugin is built.
Now the plugin is ready for use, but our Instrument Cluster application doesn't know where to
search for it and is still using the old hardcoded registration. So, we can now remove the
linking step in the \c instrument-cluster.pro file and change our main file accordingly:
\quotefromfile ivicore/qface-tutorial/chapter3-simulation-backend/instrument-cluster/main.cpp
\skipto #include
\printuntil }
What has changed is that we've now added an additional import path with the \c addImportPath
function, which points to the "imports" folder next to the binary's location.
\target chapter4
\section1 Chapter 4: Add a Custom Simulation
So far, we've created a Middleware API and integrated it into our Instrument Cluster QML code,
extended it with a QML plugin, and generated a simulation backend. In the background, quite a
lot has happened to support us; but on the UI side not much has changed till now. This chapter
is about bringing our simulation backend to life by defining sane default values and starting
to simulate a real car ride.
\section2 Define Default Values
We start by defining default values for our properties, using annotations in our QFace file.
An annotation is a special kind of comment which adds extra data to an interface, method,
property, and so on. For this use case we use the \c config_simulator annotation. For more
information, see \l{annotations-yaml}{Annotations}.
Currently, in our Instrument Cluster, the temperatur defaults to 0. Let's change this to a
temperature in spring, 15 degrees Celsius, with the following YAML fragment:
\quotefromfile ivicore/qface-tutorial/chapter4-simulation-behavior/instrument-cluster.qface
\printuntil }
Compile the plugin again for this temperature change to be reflected in our Instrument Cluster.
Let's see how this actually works: when starting the IVI Generator, the config_simulator
annotation was transformed into a JSON file that's now part of the "simulation backend" build
folder. This JSON file looks like this:
\quotefile ivicore/qface-tutorial/chapter4-simulation-behavior/backend_simulator/instrumentcluster.json
But how is this JSON file related to the actual simulation backend code? The autogenerated
simulation backend code uses QIviSimulationEngine, that reads the JSON file and provides its
data to a QML simulation file. A default QML file is also autogenerated and loaded from the
QIviSimulationEngine. This default QML file provides the behavior of what should happen in the
the simulation backend.
Later, in the next section, we take a look at the QML file and how we can change it. But first,
let's see how we can change the default values in a more dynamic way.
The QIviSimulationEngine allows us to override which JSON file should be loaded into the
engine, when we set the \c QTIVI_SIMULATION_DATA_OVERRIDE environment variable. Since there can
be multiple engines run by different backends, we need to define which engine we're referring
to. In the autogenerated code, the module name is always used as the engine specifier. For this
chapter, we already prepared a second JSON file which is part of our source directory. Setting
the environment variable as follows, changes the \c systemType to mph instead of km/h:
\badcode
QTIVI_SIMULATION_DATA_OVERRIDE=instrumentcluster=<path-to-file>/miles.json
\endcode
\section2 Define a QML Behavior
Before we define our custom behavior, let's see what's been autogenerated for us. There are two
QML files: The first is \c instrumentcluster_simulation.qml and rather simple. It defines an
entry point that istantiates the second file, an \c InstrumentClusterSimulation.qml file. This
split is done as there can be multiple interfaces defined as part of the same module.
\note A QML Engine can only have one entry point. While QIviSimulationEngine has this same
limitation, if you have a module with multiple interfaces, you want to have multiple simulation
files -- one per interface. This is why the first QML file merely instantiates the QML files for
all interfaces that it supports. In the case of our example, it's only one interface.
The InstrumentClusterSimulation.qml file is very interesting:
\quotefile ivicore/qface-tutorial/chapter4-simulation-behavior/backend_simulator/InstrumentClusterSimulation.qml
First, there's a \c settings property, that's initialized with the return value from the
\l{IviSimulator::findData}{IviSimulator.findData} method, which takes the
\l{IviSimulator::simulationData}{IviSimulator.simulationData} and a string as input. The
\c simulationData is the JSON file represented as a JavaScript object.
The \c findData method helps us to extract only the data that is of interest for this
interface, \c InstrumentCluster. The properties that follow help the interface to know whether
the default values are set. The \c LoggingCategory is used to identify the log output from this
simulation file.
Afterwards, the actual behavior is defined by instantiating an \c InstrumentClusterBackend Item
and extending it with more functions. The \c InstrumentClusterBackend is the interface towards
our \c InstrumentCluster QML frontend class. But, apart from the frontend, these properties are
also writable to make it possible to change them to provide a useful simulation.
Each time a frontend instance connects to a backend, the \c initialize() function is called.
The same applies to the QML simulation: as the \c initialize() C++ function forwards this to
the QML instance. This also applies to all other functions, like setter and getters, for
properties or methods. For more details, see \l{QIviSimulationEngine}.
Inside the QML \c initialize() function, we call \c{IviSimulator.initializeDefault()}, to read
the default values from the \c simulationData object and initialize all properties. This is
done only \b once, as we don't want the properties be reset to default when the next frontend
instance connects to the backend. Lastly, the base implementation is called to make sure that
the \c initializationDone signal is sent to the frontend.
Similarly, a setter function is defined for each property; they use the
\c{IviSimulator.checkSettings()} to read specific constraint settings for the property from
the \c simulationData and check whether these constraints are valid for the new value. If
these constraints aren't valid, then \c{IviSimulator.constraint()} is used to provide a
meaningful error message to the user.
\section2 Define Our Own QML Simulation
As mentioned above, the \c InstrumentClusterBackend Item does provide all the properties of our
QFace file. This can be used to simulate a behavior by changing the properties to the values
we want. The simplest form for this would be value assignment, but this would be rather static
not exactly what we'd like to achieve. Instead, we use QML Animation objects to change the
values over time:
\quotefromfile ivicore/qface-tutorial/chapter4-simulation-behavior/backend_simulator/simulation.qml
\skipto NumberAnimation
\printuntil }
The code snippet above changes the speed property to 80 over 4000 seconds and simulates an
accelerating car. Extending this to the other properties, and combining both sequential and
parallel animations, we can create a full simulation:
\quotefromfile ivicore/qface-tutorial/chapter4-simulation-behavior/backend_simulator/simulation.qml
\skipto property var animation
\printuntil property: "fuel"
\printuntil property: "fuel"
\printuntil }
\printuntil }
Then, to provide a nice simulation for the \c rpm property, we use a binding which does some
calculations based on the current speed. The complete simulation file looks like this:
\quotefromfile ivicore/qface-tutorial/chapter4-simulation-behavior/backend_simulator/simulation.qml
\skipto import
The next step is to tell the IVI Generator and the QIviSimulationEngine about our new
simulation file. Similar to QML files, the best aproach here is to put the simulation file into
a resource file. In our example, we add a new file called \c simulation.qrc which contains our
\c simulation.qml using the \c{/} prefix.
In our QFace file, this location now needs to be added in the form of an annotation:
\quotefromfile ivicore/qface-tutorial/chapter4-simulation-behavior/instrument-cluster.qface
\printuntil module
\dots
Now, rebuilding the simulation backend embeds the simulation file into the plugin and hands the
file over to the QIviSimulationEngine, which starts the simulation when loaded.
\target chapter5
\section1 Chapter 5: Add a Simulation Server Combined with QtRemoteObjects
In this chapter we extend our Instrument Cluster to use an Inter-Process Communication (IPC)
mechanism and use two processes. At the moment, the simulation is loaded as a plugin that
causes it to be part of the same service. Although this is good enough for a small example
application, it's not how it's done in modern multi-process architectures, where multiple
processes need to be able to access the same value and react to changes. We could write a
second Application that uses the same Middleware API. However, we can achieve the same thing
just by starting the Instrument Cluster twice and checking whether the animations are in sync.
Currently, they're not.
\image examples_qface_tutorial_unsync.gif
\section2 Add a QtRemoteObjects Integration
The IPC for this example is QtRemoteObjects, because the IVI Generator already supports it
out of the box. To use QtRemoteObjects we generate a second plugin, a "production" backend,
this time. Production backends are automatically preferred over the simulation backend we
introduced before.
This is done with the following project, \c{.pro}, file:
\quotefromfile ivicore/qface-tutorial/chapter5-ipc/backend_qtro/backend_qtro.pro
\printto CONFIG += install_ok
This \c{.pro} file is almost identical to the one we used earlier for our simulation backend.
For now we highlight what's changed.
The name of the plugin doesn't end with "_simulation" to indicate that this is a "production"
backend. The \c QFACE_FORMAT is now changed to "backend_qtro" to generate a backend that uses
QtRemoteObjects Replicas to connect to a QtRemoteObjects Source that provides the values. In
addition to a QtRemoteObject-based backend, we also need a QtRemoteObject-based server. This
part can also be autogenerated using the IVI Generator in a similar fashion:
\quotefromfile ivicore/qface-tutorial/chapter5-ipc/simulation_server/simulation_server.pro
\printto RESOURCES
Because we'd like to generate a server binary, the \c TEMPLATE needs to be set to "app" instead
of "lib". Similar to the plugin, the server also needs to link against our library to give it
access to the defined enums, structures, and other types. The template we use to generate a
simulation server is called "server_qtro_simulator".
\section2 Reuse the Existing Simulation Behavior
Now, if you start the server and then the Instrument Cluster, you don't see the simulation
from our previous chapter anymore. The reason for this, is that the simulation code is part of
our simulation backend, but this backend is no longer used as we added the
QtRemoteObjects-based "production" backend.
Because we used the "server_qtro_simulator" generation template, this can easily be fixed, as
the generated server code is also using the QIviSimulationEngine and supports to use the same
simulation file than our simulation backend. We just need to extend the project file in the
same way as we did before and are also able to use the same resource file for this.
\quotefromfile ivicore/qface-tutorial/chapter5-ipc/simulation_server/simulation_server.pro
\skipto RESOURCES
\printuntil RESOURCES
In the same way, we can also use the other simulation data JSON file that we defined in the
previous chapter, by using the same environment variable. We just need to pass it to the
server instead of our Instrument Cluster application.
Let's do the final test: starting two Instrument Cluster instances should now show the
animations in sync:
\image examples_qface_tutorial_sync.gif
\target chapter6
\section1 Chapter 6: Develop a Production Backend with D-Bus
Previously, we extended our Instrument Cluster code by using QtRemoteObjects as IPC and
autogenerated a backend for it, as well as a server that provides the simulation. In this
chapter, we'd like to write our own backend \b manually using D-Bus as IPC.
We've already prepared a working D-Bus server which provides limited simulation.
First, let's look at the server code and see what's done there; then write the backend that
connects to it.
\section2 D-Bus Server
As mentioned above, we use D-Bus for this chapter and we already have an XML file that
describes the D-Bus interface, similar to our QFace file:
\quotefile ivicore/qface-tutorial/chapter6-own-backend/demo_server/instrumentcluster.xml
This XML file is used to let qmake generate a base class which is extended by the server with
actual functionality. For more information, see \l{QtDBus}.
Our D-Bus server starts on the session bus, on the \c{/} path, and provides an interface named
"Example.IVI.InstrumentCluster". To simulate some values, we keep it simple and use a timer
event to change the speed value every 100 milliseconds. Then, we start from 0, once the
maximum of 250 is reached. Similarly, the \c rpm value is increased to 5000. For all other
properties, we provide hardcoded values.
\quotefromfile ivicore/qface-tutorial/chapter6-own-backend/demo_server/instrumentcluster.cpp
\skipto timerEvent
\printuntil }
\section2 Write Our own D-Bus Backend
Let's start with a \c{.pro} file for our backend. This is very similar to previous \c{.pro}
files, but it doesn't use the IVI Generator. Instead, it uses \c DBUS_INTERFACES to
autogenerate some client code which sends and receives messages over D-Bus.
Now, we need to define an entry point for our plugin. This plugin class needs to derive from
QIviServiceInterface and implement two functions:
\list
\li \c {QStringList interfaces()} -- that returns a list of all interfaces this plugin
supports.
\li \c {QIviFeatureInterface *interfaceInstance(const QString &interface)} -- that returns
an instance of the requested interface.
\endlist
Additionally, we also need to provide a list of interfaces we support as plugin metadata, in
the form of a JSON file which looks like this:
\quotefile ivicore/qface-tutorial/chapter6-own-backend/backend_dbus/instrumentcluster_dbus.json
We need this list, as it gives QtIvi the chance to know which interfaces a backend supports,
before instantiating it and loading only the plugins which the application code needs.
Our plugin code looks like this:
\quotefromfile ivicore/qface-tutorial/chapter6-own-backend/backend_dbus/instrumentclusterplugin.cpp
\skipto #include
\printto
In \c interfaces() we use the IID which is defined in \c{instrumentclusterbackendinterface.h}
from our autogenerated library. In \c insterfaceInstance() we check for the correct string and
return an instance of the instrument cluster backend we implemented.
This backend is defined in \c instrumentclusterbackend.h and derives from
\c InstrumentClusterBackendInterface. In our \c InstrumentClusterBackend class, we need to
implement all pure virtual functions from InstrumentClusterBackendInterface and derived classes.
For our example, this isn't complex, as we just need to implement the initialize() function.
If our XML file would use writable properties or methods, then we'd need to implement those as
well. We don't need to implement getters for our properties, because QtIvi uses the changed
signals during the initialization phase to get information about the current state. Although
the generated D-Bus interface class would provide getters to retrieve the properties from our
server, it's not recommended to use these when you develop a backend. These getters are
implemented by using synchronous calls, which means they will block the event loop until an
answer is received by the client. Since this can lead to performance issues, we recommend to
use \b asynchronous calls instead.
In our backend, we define a fetch function for each property that's implemented like this:
\quotefromfile ivicore/qface-tutorial/chapter6-own-backend/backend_dbus/instrumentclusterbackend.cpp
\skipto ::fetchSpeed
\printto ::fetchRpm
First, we add the property to a list, to know which properties have been fetched successfully.
Next, we use the \c asyncCall() function to call the getter for the \c speed property and use a
\c QDBusPendingCallWatcher to wait for the result. Once the result is ready, the lambda removes
the property again from our \c fetchList, uses the \c onSpeedChanged() function to store the
value and notifies the frontend about it. Since we don't need the watcher anymore, we delete it
in the next event loop run using \c deleteLater(), and call the \c checkInitDone() function.
The \c checkInitDone() function is defined as follows:
\quotefromfile ivicore/qface-tutorial/chapter6-own-backend/backend_dbus/instrumentclusterbackend.cpp
\skipto ::checkInitDone
\printto onSpeedChanged
It ensures that the \c initializationDone() signal is sent to the frontend once all our
properties are fetched from the server, and the initialization is complete.
In addition to retrieving the current state from the server, we also need to inform our frontend
every time a property changes. This is done by emitting the corresponding change signal when the
server changes one of its properties. To handle this, we define a slot for each property. This
slot saves the property in our class an emits the change signal:
\quotefromfile ivicore/qface-tutorial/chapter6-own-backend/backend_dbus/instrumentclusterbackend.cpp
\skipto void InstrumentClusterBackend::onSpeedChanged(int speed)
\printto onRpmChanged
The same slot is also used during the initialization phase to save and emit the value.
You might wonder why saving the value is needed at all, if we can just emit the signal. This is
because the backend plugin is used directly by every instance of the \c InstrumentCluster class
and every instance calls the \c initialize() function to retrieve the current state. Instead of
fetching all properties again, the second \c initialize() call just emits values that were
already saved; and the slots keep them up to date.
Now, when we start the Instrument Cluster, our backend should connect to our D-Bus server and
look like this:
\image examples_qface_tutorial_dbus.gif
*/
|