/****************************************************************************
**
** 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 QtInterfaceFramework 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 InterfaceFramework} 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 \l {Neptune 3 UI - Middleware}{middleware}
    services: \c remotesettings-server and \c 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 \c neptune3-ui and afterwards \c 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 \c 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
    \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.
*/