doc: Add CoAP high-level description
Add high-level documentation for CoAP library.
Signed-off-by: Ravi kumar Veeramally <ravikumar.veeramally@linux.intel.com>
diff --git a/doc/reference/networking/coap.rst b/doc/reference/networking/coap.rst
index 84b8496..848a8f4 100644
--- a/doc/reference/networking/coap.rst
+++ b/doc/reference/networking/coap.rst
@@ -6,6 +6,177 @@
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
*************
