Add documentation for Qt CoAP overviewv5.13.0-beta3

Change-Id: I1ebf03d68c267f87ca2b690d4c666c26717f8d07
Reviewed-by: Leena Miettinen <riitta-leena.miettinen@qt.io>
Reviewed-by: Edward Welbourne <edward.welbourne@qt.io>
Reviewed-by: Alex Blasche <alexander.blasche@qt.io>

3 files changed, 209 insertions, 2 deletions

diff --git a/src/coap/doc/src/external-resources.qdoc b/src/coap/doc/src/external-resources.qdoc
index f09e94a..8cbbf9f 100644
--- a/src/coap/doc/src/external-resources.qdoc
+++ b/src/coap/doc/src/external-resources.qdoc
@@ -31,6 +31,26 @@
 */
 
 /*!
+    \externalpage https://tools.ietf.org/html/rfc7252
+    \title RFC 7252
+*/
+
+/*!
+    \externalpage https://tools.ietf.org/search/rfc7390
+    \title RFC 7390
+*/
+
+/*!
+    \externalpage https://tools.ietf.org/search/rfc7959
+    \title RFC 7959
+*/
+
+/*!
+    \externalpage https://tools.ietf.org/search/rfc7641
+    \title RFC 7641
+*/
+
+/*!
     \externalpage https://tools.ietf.org/search/rfc7390#section-2.5
     \title RFC 7390 - Section 2.5
 */
diff --git a/src/coap/doc/src/qtcoap-index.qdoc b/src/coap/doc/src/qtcoap-index.qdoc
index b40e7d6..ed0795e 100644
--- a/src/coap/doc/src/qtcoap-index.qdoc
+++ b/src/coap/doc/src/qtcoap-index.qdoc
@@ -25,13 +25,36 @@
 **
 ****************************************************************************/
 
-
 /*!
     \page qtcoap-index.html
     \title Qt CoAP
     \brief Provides classes and functions to make CoAP programming simple and
     portable.
 
+    Constrained Application Protocol (\l CoAP) is a machine-to-machine (M2M) web
+    transfer protocol for use with constrained nodes and constrained networks in
+    the Internet of Things (IoT). It is designed to easily interface with HTTP for
+    integration with the Web, while meeting specialized requirements such as multicast
+    support, very low overhead, and simplicity for constrained environments.
+
+    The Qt CoAP module implements the client side of CoAP defined by \l{RFC 7252}.
+    Generally, CoAP is designed to use datagram-oriented transport such as UDP, so
+    the current implementation of the transport is based on UDP. However implementing
+    custom transports based on TCP, WebSocket, and so on, is also possible.
+
+    The Qt CoAP module supports:
+
+    \list
+    \li Security based on Datagram TLS (DTLS) over UDP
+    \li Group communication defined by \l{RFC 7390}
+    \li Blockwise transfers defined by \l{RFC 7959}
+    \li Resource observation defined by \l{RFC 7641}
+    \li Resource discovery (multicast and single server)
+    \endlist
+
+    \note Qt CoAP is part of the Qt for Automation offering and not Qt. For further
+    details please see \l {Qt for Automation}.
+
     \section1 Getting Started
 
     To include the definitions of the module's classes, use the following
diff --git a/src/coap/doc/src/qtcoap-overview.qdoc b/src/coap/doc/src/qtcoap-overview.qdoc
index 3122b4b..5400362 100644
--- a/src/coap/doc/src/qtcoap-overview.qdoc
+++ b/src/coap/doc/src/qtcoap-overview.qdoc
@@ -25,9 +25,173 @@
 **
 ****************************************************************************/
 
-
 /*!
     \page qtcoap-overview.html
     \title Qt CoAP Overview
     \brief Provides insight into the CoAP protocol and the Qt CoAP module.
+
+    Constrained Application Protocol (CoAP) is an IoT protocol that is specifically
+    designed for M2M data exchange between constrained devices (such as microcontrollers)
+    in constrained networks.
+
+    The interaction model of CoAP is similar to the client/server model of HTTP, but
+    unlike HTTP, it uses datagram-oriented connectionless transport such as UDP, which
+    leads to a very low overhead and allows UDP broadcast and multicast to be used
+    for addressing. At the same time it provides lightweight reliability mechanisms
+    and security.
+
+    Qt CoAP implements the client side of CoAP. By default, the transport layer uses
+    QUdpSocket and QDtls for security. Alternative transports can be used by implementing
+    the QCoapConnection interface.
+
+    \section1 Messaging Model
+
+    The CoAP messaging model is based on the exchange of messages between endpoints:
+    clients make requests to servers; servers send back responses. Clients may \e GET,
+    \e PUT, \e POST and \e DELETE resources. They can also discover resources on a server
+    by making discovery requests, or in the local network, by making multicast discovery
+    requests. It is also possible to subscribe to a resource, with an observe request.
+
+    Reliability of the transfer is achieved by marking a message \e confirmable (CON).
+    A confirmable message is retransmitted using a default timeout and exponential
+    back-off between retransmissions, until the recipient sends an \e acknowledgment
+    (ACK) message. When the recipient is not able to process a confirmable message,
+    it replies with a \e reset message (RST) instead of an acknowledgment.
+
+    A message that does not require reliable transmission can be sent as a
+    \e non-confirmable (NON) message.
+
+    \section1 Using the Qt CoAP API
+
+    The communication of the client with the CoAP server is done using the QCoapClient
+    class. It contains the methods for sending different CoAP requests and the signals
+    that get triggered when the replies for the sent request arrive. The QCoapRequest
+    class is used for creating CoAP requests. The response from the server is returned
+    in a QCoapReply object. For example:
+
+    \code
+    QCoapClient *client = new QCoapClient();
+    connect(client, &QCoapClient::finished, this, &MyClass::onFinished);
+    connect(client, &QCoapClient::error, this, &MyClass::onError);
+
+    QCoapRequest request(QUrl("coap://127.0.0.1/test"), QCoapMessage::Confirmable);
+    client->get(request);
+    client->put(request, QByteArray("payload"));
+
+    \endcode
+
+    \section1 Supported Features
+
+    \section2 Resource Discovery
+
+    CoAP discovery requests are used to query the resources available on an endpoint
+    or in the complete network. This is really important for M2M applications, where
+    there are no humans in the loop. For example, for home or building automation,
+    there is a need for local clients and servers to find and interact with each other
+    without human intervention. Resource discovery allows clients to learn about
+    the endpoints available in the network.
+
+    Qt CoAP supports discovery requests to a single endpoint and to multicast groups.
+    For example, a discovery request to \c /.well-known/core, which is the default
+    resource discovery entry point, may return something like:
+
+    \badcode
+    RES: 2.05 Content
+    </sensors/temp>;rt="temperature-c";if="sensor";obs,
+    </sensors/light>;rt="light-lux";if="sensor",
+    </firmware/v2.1>;rt="firmware";sz=262144
+    \endcode
+
+    Indicating that there are resources for temperature and light sensors and a
+    firmware resource available in the network. The reply is represented in
+    \l {https://tools.ietf.org/html/rfc6690}{CoRE Link Format}.
+
+    The specialized QCoapDiscoveryReply class is used to get the discovery replies:
+
+    \code
+    // This will make a multicast discovery request to the CoAP IPv4 multicast group.
+    QCoapDiscoveryReply *discoverReply = client->discover();
+    connect(discoverReply, &QCoapDiscoveryReply::discovered, this, &MyClass::onDiscovered);
+    \endcode
+
+    The QCoapDiscoveryReply::discovered will return the list of CoAP resources found in the
+    network.
+
+    \section2 Resource Observation
+
+    Observe requests are used to receive automatic server notifications for a resource.
+    The client becomes an observer of an observable resource by sending an observe request
+    to the resource. For example, the temperature sensor from the above example is observable,
+    because it has the \c obs attribute. So the client can subscribe to the temperature updates
+    by sending an observe request to it.
+
+    The following example code shows how to send observe requests using Qt CoAP:
+
+    \code
+    QCoapReply *reply = client->observe(QUrl("127.0.0.1/temp"));
+    connect(reply, &QCoapReply::notified, this, &MyClass::onNotified);
+    \endcode
+
+    For Observe requests specifically, you can use the QCoapReply::notified signal to handle
+    notifications from the CoAP server.
+
+    \section2 Blockwise Transfers
+
+    Since CoAP is based on datagram transports such as UDP, there are limits on how big
+    a resource representation can be, to be transferred without fragmentation causing
+    problems. Qt CoAP supports block-wise transfers for situations where a resource
+    representation is larger than can be comfortably transferred in the payload of a single
+    CoAP datagram.
+
+    \section2 Security
+
+    The following security modes are defined for CoAP:
+
+    \list
+        \li \b {Pre-Shared Key} - in this mode the client must send to the server its identity
+        and the pre-shared key.
+
+        \li \b {Raw Public Key} - the client has an asymmetric key pair without a certificate
+        (a raw public key). The client also has an identity calculated from the public key and
+        a list of identities of the nodes it can communicate with. Qt CoAP has not implemented
+        this mode yet.
+
+        \li \b Certificate - the client has an asymmetric key pair with an X.509 certificate
+        that is signed by some common trust root.
+    \endlist
+
+    Since CoAP is designed to be a UDP-based protocol, Qt CoAP module implements security
+    based on Datagram TLS (DTLS) over UDP. However, as mentioned above, it is possible to
+    provide a custom transport with another security type.
+
+    For securing the CoAP client, one of the supported security modes should be specified
+    when creating the client:
+
+    \code
+    QCoapClient *client = new QCoapClient(this, QtCoap::PreSharedKey);
+    \endcode
+
+    The QCoapSecurityConfiguration class is used for specifying the security parameters.
+    For example, in pre-shared key mode the following example code can be used:
+
+    \code
+    QCoapSecurityConfiguration config;
+    config.setPreSharedKey("secretPSK");
+    config.setIdentity("Client_identity");
+    client->setSecurityConfiguration(config);
+    \endcode
+
+    And in certificate mode:
+    \code
+    QCoapClient *client = new QCoapClient(this, QtCoap::Certificate);
+    QVector<QSslCertificate> localCertificates, caCertificates;
+    QCoapPrivateKey key;
+    // Initialize the key and certificates
+    QCoapSecurityConfiguration config;
+    config.setLocalCertificateChain(localCertificates);
+    config.setCaCertificates(caCertificates)
+    config.setPrivateKey(key);
+    client->setSecurityConfiguration(config);
+
+    \endcode
 */