1.. zephyr:code-sample:: coap-download
2   :name: CoAP download
3   :relevant-api: coap
4
5   Use the CoAP client API to download data via a GET request
6
7Overview
8********
9
10This sample demonstrates the use of the CoAP client API to make GET requests to
11a CoAP server. If the data to be fetched is larger than a single CoAP packet,
12a blockwise transfer will be used to receive the data.
13
14Once the transfer is complete, the sample prints the amount of data received
15and the time taken.
16
17Requirements
18************
19- :ref:`networking_with_host`, :ref:`networking_with_native_sim`
20- or, a board with hardware networking (tested on nucleo_h753zi)
21- Network connection between the board and host running a CoAP server
22
23Build and Running
24*****************
25Build the CoAP download sample application like this:
26
27.. zephyr-app-commands::
28   :zephyr-app: samples/net/sockets/coap_download
29   :board: <board to use>
30   :conf: <config file to use>
31   :goals: build
32   :compact:
33
34The easiest way to run this sample application is to build and run it as a
35native_sim application. Some setup is required as described in
36:ref:`networking_with_native_sim`.
37
38Download a CoAP server application, for example `aiocoap`_ (Python), or
39`Eclipse Californium`_ (Java) has a demo `Simple File Server`_ application.
40
41Using ``aiocoap``:
42
43.. code-block:: bash
44
45    python -m pip install "aiocoap[all]"
46    mkdir file_root
47    echo "some test data" > file_root/test.txt
48    aiocoap-fileserver file_root
49
50You can also change the name of the CoAP resource to request via Kconfig:
51
52.. code-block:: cfg
53
54    CONFIG_NET_SAMPLE_COAP_RESOURCE_PATH="resource_name_to_request"
55
56Launch :command:`net-setup.sh` in net-tools:
57
58.. code-block:: bash
59
60   ./net-setup.sh
61
62Build and run the coap_download sample application for native_sim like this:
63
64.. zephyr-app-commands::
65   :zephyr-app: samples/net/sockets/coap_download
66   :host-os: unix
67   :board: native_sim
68   :goals: run
69   :compact:
70
71Sample output
72=============
73
74.. code-block:: console
75
76    [00:00:00.000,000] <inf> net_config: Initializing network
77    [00:00:00.000,000] <inf> net_config: IPv4 address: 192.0.2.1
78    [00:00:00.110,000] <inf> net_config: IPv6 address: 2001:db8::1
79    [00:00:00.110,000] <inf> net_config: IPv6 address: 2001:db8::1
80    [00:00:00.110,000] <inf> coap_download: Network L4 is connected
81    [00:00:00.110,000] <inf> coap_download: Starting CoAP download using IPv4
82    [00:00:00.180,000] <inf> coap_download: CoAP response, result_code=69, offset=0, len=100
83    [00:00:00.180,000] <inf> coap_download: CoAP download done, got 100 bytes in 70 ms
84    [00:00:00.180,000] <inf> coap_download: Starting CoAP download using IPv6
85    [00:00:00.300,000] <inf> coap_download: CoAP response, result_code=69, offset=0, len=100
86    [00:00:00.300,000] <inf> coap_download: CoAP download done, got 100 bytes in 120 ms
87
88.. _aiocoap: https://github.com/chrysn/aiocoap
89.. _Eclipse Californium: https://github.com/eclipse-californium/californium
90.. _Simple File Server: https://github.com/eclipse-californium/californium/tree/main/demo-apps/cf-simplefile-server
91