/****************************************************************************
**
** Copyright (C) 2018 The Qt Company Ltd.
** Contact: https://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 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 qtknx-overview.html
    \title Qt KNX Overview
    \brief An overview of the Qt KNX module.

    \l{KNX} is a standard for controlling home and building management equipment,
    such as: lighting, blinds and shutters, security systems, energy management,
    heating, ventilation and air-conditioning systems, signaling and monitoring
    systems, interfaces to service and building control systems, remote control,
    metering, audio and video control.

    Qt KNX implements the client side of a connection between a client and a
    KNXnet/IP server. This connection enables sending messages to the KNX bus
    and controlling the functionalities of the KNX devices. Only local device
    management procedures and KNX application services working with group
    addressing are fully supported.

    \section1 KNXnet/IP Server Communication

    The first step in the communication process between a client and a KNXnet/IP
    server is to discover the KNXnet/IP server. This can be done using the class
    \l QKnxNetIpServerDiscoveryAgent. If the description of the server during
    the discovery is not enough, it is possible to learn more about a particular
    server using the class \l QKnxNetIpServerDescriptionAgent.

    \section2 Creating Connections

    Once the server is discovered, in order to send messages to the KNX devices,
    a connection must be established with the server data endpoints. The client
    requests this connection by using the server's control endpoint.

    Depending on the client's goal, different connections have to be opened.
    If the client wants to access the management functionalities of the
    KNXnet/IP server, the class \l QKnxNetIpDeviceManagement takes care of
    opening and maintaining the connection. If the client wants to access the
    functionalities of a KNX device on the bus behind the KNXnet/IP server, the
    class \l QKnxNetIpTunnel takes care of the connection.

    For more information, see \l {Qt KNX Device Management Classes} and
    \l {Qt KNX Tunneling Classes}.

    \section2 Sending Frames

    Frames can be sent to the KNXnet/IP server by using \l QKnxNetIpTunnel or
    \l QKnxNetIpDeviceManagement. With the former, \l QKnxLinkLayerFrame objects
    are sent and with the latter, \l QKnxDeviceManagementFrame objects are sent.

    To help build the frames, the following classes are provided:

     \list
        \li \l QKnxLinkLayerFrame::Builder
        \li \l QKnxDeviceManagementFrame::Builder
        \li \l QKnxDeviceManagementFrame::PropertyReadBuilder
        \li \l QKnxDeviceManagementFrame::PropertyWriteBuilder
        \li \l QKnxDeviceManagementFrame::PropertyInfoBuilder
        \li \l QKnxDeviceManagementFrame::FunctionPropertyCommandBuilder
        \li \l QKnxDeviceManagementFrame::FunctionPropertyStateReadBuilder
        \li \l QKnxDeviceManagementFrame::ResetBuilder
    \endlist

    \l QKnxDeviceManagementFrame objects are dedicated to the KNXnet/IP
    device management. Sending those frames allows access to the server's
    interface objects. The \l QKnxInterfaceObjectType holds the type of
    an interface object. The objects themselves hold the properties and
    functionalities of the server.
    The client can use \l QKnxDeviceManagementFrame to read and write the
    values in the server's interface objects.

    \l QKnxLinkLayerFrame objects are sent to the KNX devices on the bus,
    behind the KNXnet/IP server. To build the frames, the following are needed:

    \list
        \li The address that the frame has to be sent to, represented by
            \l QKnxAddress.
        \li The KNX application service the client wants to use. For a list
            of available services, see \l QKnxTpdu::ApplicationControlField.
        \li The data. Needed if a write service is being triggered.
    \endlist

    \section3 Link Layer Frame Addresses

    The link layer frame destination address \l QKnxAddress can be individual
    or a group (see \l QKnxAddress::Type). An individual address targets a
    specific device on the bus. A group address targets one or several instances
    of a datapoint.

    A datapoint represents a device functionality. Datapoint types are held by
    \l QKnxDatapointType. To be grouped under the same  group address, datapoint
    instances, also called group objects, must be of the same type. The group
    addresses and the group objects they represent are defined in the KNX
    project file.

    \section3 KNX Application Service

    The KNX application service and data are encapsulated in the \l QKnxTpdu
    part of \l QKnxLinkLayerFrame.

    \section3 Datapoints

    The data is the representation of the device functionality. It is the bits
    corresponding to a given group object or interface object property.

    If the client is addressing a group object, the \l QKnxByteArray data is
    easily built using the appropriate \l QKnxDatapointType type. The group
    object is a realization of a datapoint at the level of the device. To
    create data corresponding to a given datapoint, one must know the type of
    the datapoint.

    The datapoint type is found in the KNX project file where the group address
    is described. The main and sub-number of the datapoint indicate its type.
    The class \l QKnxDatapointTypeFactory can create the
     \l QKnxDatapointType corresponding to those two numbers.

    \section2 Example

    For example, a client has a tunnel connection in place and wants to turn on
    a lamp. From the KNX project file, the client knows the switch of the lamp
    is linked to the group address 2/6/4 and that the main- and sub-number of
    the corresponding datapoint type are 1.1.

    \code
        QKnxNetIpTunnel connection;
        connection.connectToHost(QHostAddress(...), port);

        QKnxLinkLayerFrame frame = QKnxLinkLayerFrame::builder()
            .setDestinationAddress({ QKnxAddress::Type::Group, QLatin1String("2/6/4") })
            .setTpdu({
                QKnxTpdu::TransportControlField::DataGroup,
                QKnxTpdu::ApplicationControlField::GroupValueWrite,
                QKnxSwitch(QKnxSwitch::State::On).bytes()
            }).create();

        connection.sendFrame(frame);
    \endcode
*/
