// Copyright (C) 2018 Andre Hartmann <aha_1980@gmx.de>
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
/*!
    \page qtserialbus-virtualcan-overview.html
    \title Using VirtualCAN Plugin

    \brief Overview of how to use the VirtualCAN plugin.

    The VirtualCAN plugin allows testing of CAN applications with a local
    TCP/IP connection without CAN hardware. The TCP server is created,
    when the first client calls createDevice(). The default TCP port is
    35468, which can be changed by giving the fully qualified URL to
    createDevice(). Once the server is running, no further server is
    started on the same system.

    Afterwards, all clients send their CAN frames to the server, which
    distributes them to the other clients.

    \section1 Creating CAN Bus Devices

    At first it is necessary to check that QCanBus provides the desired plugin:

    \code
        if (QCanBus::instance()->plugins().contains(QStringLiteral("virtualcan"))) {
            // plugin available
        }
    \endcode

    Where \e virtualcan is the plugin name.

    Next, a connection to a specific interface can be established:

    \code
        QCanBusDevice *device = QCanBus::instance()->createDevice(
            QStringLiteral("virtualcan"), QStringLiteral("can0"));
        device->connectDevice();
    \endcode

    Where \e can0 is the active CAN channel name. The VirtualCAN plugin
    provides two channels "can0" and "can1". Both can be used as CAN 2.0
    or CAN FD channels. All applications connected to one of these channels
    receive all messages that are sent to this channel.

    To connect to a remote server, use the following fully qualified URL
    as interface name:

    \code
        tcp://server:port/canX
    \endcode

    for example:

    \code
        tcp://192.168.1.2:35468/can0
    \endcode

    The device is now open for writing and reading CAN frames:

    \code
        QCanBusFrame frame;
        frame.setFrameId(8);
        QByteArray payload("A36E");
        frame.setPayload(payload);
        device->writeFrame(frame);
    \endcode

    The reading can be done using the \l {QCanBusDevice::}{readFrame()} method. The
    \l {QCanBusDevice::}{framesReceived()} signal is emitted when at least one new
    frame is available for reading:

    \code
        QCanBusFrame frame = device->readFrame();
    \endcode

    VirtualCAN supports the following configurations that can be controlled through
    \l {QCanBusDevice::}{setConfigurationParameter()}:

    \table
        \header
            \li Configuration parameter key
            \li Description
        \row
            \li QCanBusDevice::CanFdKey
            \li Determines whether the virtual CAN bus operates in CAN FD mode or not.
                This option is disabled by default.
        \row
            \li QCanBusDevice::ReceiveOwnKey
            \li The reception of the CAN frames on the same device that was sending
                the CAN frame is disabled by default. When enabling this option,
                all CAN frames sent to the CAN bus immediately appear in the receive
                buffer. This can be used to check if sending was successful. If this
                option is enabled, the therefore received frames are marked with
                QCanBusFrame::hasLocalEcho()
   \endtable
*/
