doc: Add CoAP high-level description

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

*************