Add J2534 Pass-Thru CAN plugin

[ChangeLog] Add J2534 Pass-Thru CAN plugin

SAE J2534 is a standard for communication between a computer and
a vehicle. The "passthrucan" plugin adds support for communicating
with a vehicle's CAN bus via the generic J2534 Pass-Thru API.

The J2534 Pass-Thru API v04.04 is only specified for 32-bit Windows,
but implementations for 64-bit Windows and other platforms do exist.
Automatic device discovery is based on the Windows registry and thus
supported on Windows only. However, this plugin alternatively allows
users to specify the path to a J2534 vendor library to load.

Any CAN interface adapters that ship with a compliant J2534 Pass-Thru
interface library (v04.04) for the target platform should work with
this plugin. It should be noted though that driver support for x64 is
as of yet rare, thus a 32-bit Qt build may be required to make use of
the passthrucan plugin.

Change-Id: I55280d455828d9cf0ad03690224b924b39c17cf7
Reviewed-by: André Hartmann <aha_1980@gmx.de>
Reviewed-by: Alex Blasche <alexander.blasche@qt.io>

2 files changed, 159 insertions, 0 deletions

diff --git a/src/serialbus/doc/src/passthrucan.qdoc b/src/serialbus/doc/src/passthrucan.qdoc
new file mode 100644
index 0000000..2f29926
--- /dev/null
+++ b/src/serialbus/doc/src/passthrucan.qdoc
@@ -0,0 +1,155 @@
+/****************************************************************************
+**
+** Copyright (C) 2017 Ford Motor Company.
+** Contact: http://www.qt.io/licensing/
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:FDL$
+** Commercial License Usage
+** Licensees holding valid commercial Qt 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 http://www.qt.io/terms-conditions. For further
+** information use the contact form at http://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: http://www.gnu.org/copyleft/fdl.html.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+/*!
+    \page qtserialbus-passthrucan-overview.html
+    \title Using PassThruCAN Plugin
+
+    \brief Overview of how to use the J2534 Pass-Thru CAN plugin.
+
+    The Pass-Thru CAN plugin accesses CAN adapters via the SAE J2534 Pass-Thru API.
+    SAE J2534 is a standard for accessing vehicle busses from an x86 Windows PC.
+    Although the API is specified only for 32-bit Windows, some vendors also provide
+    implementations for 64-bit Windows and other operating systems such as Linux.
+
+    \section1 PassThruCAN usage
+
+    To use PassThruCAN, the corresponding vendor drivers for the CAN adapter must
+    be installed. The vendor must also provide an implementation of the J2534 API
+    by way of a shared library. Currently, only version 04.04 of the Pass-Thru API
+    is supported.
+
+    When using an x64 build of Qt, this plugin only works if the CAN device vendor
+    also provides a 64-bit version of the J2534 Pass-Thru interface library. If the
+    vendor provides only a 32-bit J2534 interface, a 32-bit build of Qt is required
+    to make use of it.
+
+    For automatic device discovery, the vendor software must also list and describe
+    the available adapters in the Windows registry. On systems other than Windows,
+    automatic discovery is currently not supported.
+
+    \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("passthrucan"))) {
+            // plugin available
+        }
+    \endcode
+
+    Where \e passthrucan is the plugin name.
+
+    On Windows, automatic device discovery should be used to list the available
+    CAN adapters accessible via the Pass-Thru API:
+
+    \code
+        const auto adapters = QCanBus::instance()->
+                availableDevices(QStringLiteral("passthrucan"));
+        for (const QCanBusDeviceInfo &info : adapters) {
+            // List available adapter in the user interface.
+            uiListBox->addItem(info.name());
+        }
+    \endcode
+
+    On other operating systems, the list of discovered adapters will be empty.
+    Instead, the full path to the vendor-provided J2534 interface library
+    should be provided in lieu of the device name:
+
+    \code
+        QCanBusDevice *device = QCanBus::instance()->createDevice(
+            QStringLiteral("passthrucan"), QStringLiteral("/path/to/libj2534-vendor.so"));
+    \endcode
+
+    For special needs, it is also possible to pass a vendor-specific device
+    name argument when opening the Pass-Thru adapter:
+
+    \code
+        QCanBusDevice *device = QCanBus::instance()->createDevice(
+            QStringLiteral("passthrucan"), info.name() + QChar::fromLatin1('%') + deviceName);
+    \endcode
+
+    All operations on the Pass-Thru CAN bus device are executed asynchronously,
+    including connect and disconnect. In order to be notified when the device
+    is ready for reading and writing CAN frames, connect to the
+    \l {QCanBusDevice::}{stateChanged(QCanBusDevice::CanBusDeviceState state)}
+    signal:
+
+    \code
+        connect(device, &QCanBusDevice::stateChanged,
+                this, &MyClass::canStateChanged);
+        device->connectDevice();
+    \endcode
+
+    \l {QCanBusDevice::}{state()} will return \l {QCanBusDevice::}{ConnectedState}
+    once the CAN adapter has been successfully connected to. The device is then
+    open for writing and reading CAN frames:
+
+    \code
+        QCanBusFrame frame;
+        frame.setFrameId(8);
+        frame.setPayload(QByteArray("\xA3\x6E\x74\x9C", 4));
+        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
+
+    The Pass-Thru CAN plugin supports the following configuration options
+    controllable via \l {QCanBusDevice::}{setConfigurationParameter()}:
+
+    \table
+        \header
+            \li Configuration parameter key
+            \li Description
+        \row
+            \li QCanBusDevice::LoopbackKey
+            \li When enabled, if a CAN frame is transmitted on the CAN bus, a local
+                echo of this frame will be received by the CAN adapter. The echo
+                frames are marked with QCanBusFrame::hasLocalEcho(). By default,
+                loopback mode is disabled.
+        \row
+            \li QCanBusDevice::RawFilterKey
+            \li This option allows setting up filters for incoming CAN bus messages.
+                If provided, the value should be a \l {QList<QCanBusDevice::Filter>}.
+                Only data frame ID filters are supported. By default, data frames
+                with any ID are accepted.
+        \row
+            \li QCanBusDevice::BitRateKey
+            \li The bit rate of the CAN bus as an unsigned integer, in bit/s. The
+                default bit rate is 500000 (500 kbit/s). Setting the bit rate after
+                the device has already been connected may trigger an implicit
+                reinitialization of the CAN interface.
+    \endtable
+
+    The Pass-Thru CAN plugin supports extended frame format (29-bit IDs), but not
+    flexible data-rate (CAN FD).
+ */
diff --git a/src/serialbus/doc/src/qtcanbus-backends.qdoc b/src/serialbus/doc/src/qtcanbus-backends.qdoc
index e18adf6..1c4cd74 100644
--- a/src/serialbus/doc/src/qtcanbus-backends.qdoc
+++ b/src/serialbus/doc/src/qtcanbus-backends.qdoc
@@ -61,6 +61,10 @@
             \li \l {Using SocketCAN Plugin}{SocketCAN} (\c socketcan)
             \li CAN bus plugin using Linux sockets and open source drivers.
         \row
+            \li CAN via SAE J2534 Pass-Thru
+            \li \l {Using PassThruCAN Plugin}{PassThruCAN} (\c passthrucan)
+            \li CAN bus plugin using the SAE J2534 Pass-Thru interface.
+        \row
             \li SYS TEC electronic
             \li \l {Using SystecCAN Backend}{SystecCAN} (\c systeccan)
             \li CAN bus backend using the SYS TEC CAN adapters.