Add CoAP high-level description

doc/reference/networking/coap.rst

@@ -6,6 +6,177 @@ CoAP
 Overview
 ********
 
+The Constrained Application Protocol (CoAP) is a specialized web transfer
+protocol for use with constrained nodes and constrained (e.g., low-power,
+lossy) networks. It provides a convenient API for RESTful Web services
+that support CoAP's features. For more information about the protocol
+itself, see `IETF RFC7252 The Constrained Application Protocol <https://tools.ietf.org/html/rfc7252>`_.
+
+Zephyr provides a CoAP library which supports client and server roles.
+The library is configurable as per user needs. The Zephyr CoAP library
+is implemented using plain buffers. Users of the API create sockets
+for communication and pass the buffer to the library for parsing and other
+purposes. The library itself doesn't create any sockets for users.
+
+On top of CoAP, Zephyr has support for LWM2M “Lightweight Machine 2 Machine”
+protocol, a simple, low-cost remote management and service enablement mechanism.
+See :ref:`lwm2m_interface` for more information.
+
+Supported RFCs:
+
+Supported RFCs:
+
+- `RFC7252: The Constrained Application Protocol (CoAP) <https://tools.ietf.org/html/rfc7252>`_
+- `RFC6690: Constrained RESTful Environments (CoRE) Link Format <https://tools.ietf.org/html/rfc6690>`_
+- `RFC7959: Block-Wise Transfers in the Constrained Application Protocol (CoAP) <https://tools.ietf.org/html/rfc7959>`_
+- `RFC7641: Observing Resources in the Constrained Application Protocol (CoAP) <https://tools.ietf.org/html/rfc7641>`_
+
+.. note:: Not all parts of these RFCs are supported. Features are supported based on Zephyr requirements.
+
+Sample Usage
+************
+
+CoAP Server
+===========
+
+To create a CoAP server, resources for the server need to be defined.
+The ``.well-known/core`` resource should be added before all other
+resources that should be included in the responses of the ``.well-known/core``
+resource.
+
+.. code-block:: c
+
+    static struct coap_resource resources[] = {
+        { .get = well_known_core_get,
+          .path = COAP_WELL_KNOWN_CORE_PATH,
+        },
+        { .get  = sample_get,
+          .post = sample_post,
+          .del  = sample_del,
+          .put  = sample_put,
+          .path = sample_path
+        },
+        { },
+    };
+
+An application reads data from the socket and passes the buffer to the CoAP library
+to parse the message. If the CoAP message is proper, the library uses the buffer
+along with resources defined above to call the correct callback function
+to handle the CoAP request from the client. It's the callback function's
+responsibilty to either reply or act according to CoAP request.
+
+.. code-block:: c
+
+    coap_packet_parse(&request, data, data_len, options, opt_num);
+    ...
+    coap_handle_request(&request, resources, options, opt_num,
+                        client_addr, client_addr_len);
+
+CoAP Client
+===========
+
+If the CoAP client knows about resources in the CoAP server, the client can start
+prepare CoAP requests and wait for responses. If the client doesn't know
+about resources in the CoAP server, it can request resources through
+the ``.well-known/core`` CoAP message.
+
+.. code-block:: c
+
+    /* Initialize the CoAP message */
+    char *path = "test";
+    struct coap_packet request;
+    u8_t data[100];
+    u8_t payload[20];
+
+    coap_packet_init(&request, data, sizeof(data),
+                     1, COAP_TYPE_CON, 8, coap_next_token(),
+                     COAP_METHOD_GET, coap_next_id());
+
+    /* Append options */
+    coap_packet_append_option(&request, COAP_OPTION_URI_PATH,
+                              path, strlen(path));
+
+    /* Append Payload marker if you are going to add payload */
+    coap_packet_append_payload_marker(&request);
+
+    /* Append payload */
+    coap_packet_append_payload(&request, (u8_t *)payload,
+                               sizeof(payload) - 1);
+
+    /* send over sockets */
+
+Testing
+*******
+
+There are various ways to test Zephyr CoAP library.
+
+libcoap
+=======
+libcoap implements a lightweight application-protocol for devices that are
+resource constrained, such as by computing power, RF range, memory, bandwidth,
+or network packet sizes. Sources can be found here `libcoap <https://github.com/obgm/libcoap>`_.
+libcoap has a script (``examples/etsi_coaptest.sh``) to test coap-server functionality
+in Zephyr.
+
+See the `net-tools <https://github.com/zephyrproject-rtos/net-tools>`_ project for more details
+
+The :ref:`coap-server-sample` sample can be built and executed on QEMU as described
+in :ref:`networking_with_qemu`.
+
+Use this command on the host to run the libcoap implementation of
+the ETSI test cases:
+
+.. code-block:: console
+
+   sudo ./libcoap/examples/etsi_coaptest.sh -i tap0 2001:db8::1
+
+TTCN3
+=====
+Eclipse has TTCN3 based tests to run against CoAP implementations.
+
+Install eclipse-titan and set symbolic links for titan tools
+
+.. code-block:: console
+
+    sudo apt-get install eclipse-titan
+
+    cd /usr/share/titan
+
+    sudo ln -s /usr/bin bin
+    sudo ln /usr/bin/titanver bin
+    sudo ln -s /usr/bin/mctr_cli bin
+    sudo ln -s /usr/include/titan include
+    sudo ln -s /usr/lib/titan lib
+
+    export TTCN3_DIR=/usr/share/titan
+
+    git clone https://github.com/eclipse/titan.misc.git
+
+    cd titan.misc
+
+Follow the instruction to setup CoAP test suite from here:
+
+- https://github.com/eclipse/titan.misc
+- https://github.com/eclipse/titan.misc/tree/master/CoAP_Conf
+
+After the build is complete, the :ref:`coap-server-sample` sample can be built
+and executed on QEMU as described in :ref:`networking_with_qemu`.
+
+Change the client (test suite) and server (Zephyr coap-server sample) addresses
+in coap.cfg file as per your setup.
+
+Execute the test cases with following command.
+
+.. code-block:: console
+
+   ttcn3_start coaptests coap.cfg
+
+Sample output of ttcn3 tests looks like this.
+
+.. code-block:: console
+
+   Verdict statistics: 0 none (0.00 %), 10 pass (100.00 %), 0 inconc (0.00 %), 0 fail (0.00 %), 0 error (0.00 %).
+   Test execution summary: 10 test cases were executed. Overall verdict: pass
 
 API Reference
 *************