1.. zephyr:code-sample:: sockets-echo-server
2   :name: Echo server (advanced)
3   :relevant-api: bsd_sockets tls_credentials
4
5   Implement a UDP/TCP server that sends received packets back to the sender.
6
7Overview
8********
9
10The echo-server sample application for Zephyr implements a UDP/TCP server
11that complements the echo-client sample application: the echo-server listens
12for incoming IPv4 or IPv6 packets (sent by the echo client) and simply sends
13them back.
14
15The source code for this sample application can be found at:
16:zephyr_file:`samples/net/sockets/echo_server`.
17
18Requirements
19************
20
21- :ref:`networking_with_host`
22
23Building and Running
24********************
25
26There are multiple ways to use this application. One of the most common
27usage scenario is to run echo-server application inside QEMU. This is
28described in :ref:`networking_with_qemu`.
29
30There are configuration files for different boards and setups in the
31echo-server directory:
32
33- :file:`prj.conf`
34  Generic config file, normally you should use this.
35
36- :file:`overlay-ot.conf`
37  This overlay config enables support for OpenThread.
38
39- :file:`overlay-802154.conf`
40  This overlay config enables support for native IEEE 802.15.4 connectivity.
41  Note, that by default IEEE 802.15.4 L2 uses unacknowledged communication. To
42  improve connection reliability, acknowledgments can be enabled with shell
43  command: ``ieee802154 ack set``.
44
45- :file:`overlay-bt.conf`
46  This overlay config enables support for Bluetooth IPSP connectivity.
47
48- :file:`overlay-qemu_802154.conf`
49  This overlay config enables support for two QEMU's when simulating
50  IEEE 802.15.4 network that are connected together.
51
52- :file:`overlay-tls.conf`
53  This overlay config enables support for TLS.
54
55- :file:`overlay-tunnel.conf`
56  This overlay config enables support for IP tunneling.
57
58Build echo-server sample application like this:
59
60.. zephyr-app-commands::
61   :zephyr-app: samples/net/sockets/echo_server
62   :board: <board to use>
63   :conf: <config file to use>
64   :goals: build
65   :compact:
66
67Example building for the nrf52840dk_nrf52840 with OpenThread support:
68
69.. zephyr-app-commands::
70   :zephyr-app: samples/net/sockets/echo_server
71   :host-os: unix
72   :board: nrf52840dk_nrf52840
73   :conf: "prj.conf overlay-ot.conf"
74   :goals: run
75   :compact:
76
77Example building for the atsamr21_xpro with RF2XX driver support:
78
79.. zephyr-app-commands::
80   :zephyr-app: samples/net/sockets/echo_server
81   :host-os: unix
82   :board: [atsamr21_xpro | sam4e_xpro | sam_v71_xult]
83   :gen-args: -DEXTRA_CONF_FILE=overlay-802154.conf
84   :goals: build flash
85   :compact:
86
87In a terminal window you can check if communication is happen:
88
89.. code-block:: console
90
91    $ minicom -D /dev/ttyACM0
92
93Enabling TLS support
94====================
95
96Enable TLS support in the sample by building the project with the
97``overlay-tls.conf`` overlay file enabled, for example, using these commands:
98
99.. zephyr-app-commands::
100   :zephyr-app: samples/net/sockets/echo_server
101   :board: qemu_x86
102   :conf: "prj.conf overlay-tls.conf"
103   :goals: build
104   :compact:
105
106An alternative way is to specify ``-DEXTRA_CONF_FILE=overlay-tls.conf`` when
107running ``west build`` or ``cmake``.
108
109The certificate used by the sample can be found in the sample's ``src``
110directory. The default certificates used by Socket Echo Server and
111:zephyr:code-sample:`sockets-echo-client` enable establishing a secure connection
112between the samples.
113
114Running echo-client in Linux Host
115=================================
116
117There is one useful testing scenario that can be used with Linux host.
118Here echo-server is run in QEMU and echo-client is run in Linux host.
119
120To use QEMU for testing, follow the :ref:`networking_with_qemu` guide.
121
122Run echo-server application in QEMU:
123
124.. zephyr-app-commands::
125   :zephyr-app: samples/net/sockets/echo_server
126   :host-os: unix
127   :board: qemu_x86
128   :goals: run
129   :compact:
130
131In a terminal window:
132
133.. code-block:: console
134
135    $ sudo ./echo-client -i tap0 2001:db8::1
136
137Note that echo-server must be running in QEMU before you start the
138echo-client application in host terminal window.
139
140You can verify TLS communication with a Linux host as well. See
141https://github.com/zephyrproject-rtos/net-tools documentation for information
142on how to test TLS with Linux host samples.
143
144See the :zephyr:code-sample:`sockets-echo-client` sample documentation for an alternate
145way of running, with the echo-server on the Linux host and the echo-client
146in QEMU.
147