1.. _networking_with_native_sim:
2
3Networking with native_sim board
4################################
5
6.. contents::
7    :local:
8    :depth: 2
9
10Using virtual/TAP Ethernet driver
11*********************************
12
13This paragraph describes how to set up a virtual network between a (Linux) host
14and a Zephyr application running in a :ref:`native_sim <native_sim>` board.
15
16In this example, the :zephyr:code-sample:`sockets-echo-server` sample application from
17the Zephyr source distribution is run in native_sim board. The Zephyr
18native_sim board instance is connected to a Linux host using a tuntap device
19which is modeled in Linux as an Ethernet network interface.
20
21Prerequisites
22=============
23
24On the Linux Host, find the Zephyr `net-tools`_ project, which can either be
25found in a Zephyr standard installation under the ``tools/net-tools`` directory
26or installed stand alone from its own git repository:
27
28.. code-block:: console
29
30   git clone https://github.com/zephyrproject-rtos/net-tools
31
32
33Basic Setup
34===========
35
36For the steps below, you will need three terminal windows:
37
38* Terminal #1 is terminal window with net-tools being the current
39  directory (``cd net-tools``)
40* Terminal #2 is your usual Zephyr development terminal,
41  with the Zephyr environment initialized.
42* Terminal #3 is the console to the running Zephyr native_sim
43  instance (optional).
44
45Step 1 - Create Ethernet interface
46----------------------------------
47
48Before starting native_sim with network emulation, a network interface
49should be created.
50
51In terminal #1, type:
52
53.. code-block:: console
54
55   ./net-setup.sh
56
57You can tweak the behavior of the net-setup.sh script. See various options
58by running ``net-setup.sh`` like this:
59
60.. code-block:: console
61
62   ./net-setup.sh --help
63
64
65Step 2 - Start app in native_sim board
66--------------------------------------
67
68Build and start the ``echo_server`` sample application.
69
70In terminal #2, type:
71
72.. zephyr-app-commands::
73   :zephyr-app: samples/net/sockets/echo_server
74   :host-os: unix
75   :board: native_sim
76   :goals: run
77   :compact:
78
79
80Step 3 - Connect to console (optional)
81--------------------------------------
82
83The console window should be launched automatically when the Zephyr instance is
84started but if it does not show up, you can manually connect to the console.
85The native_sim board will print a string like this when it starts:
86
87.. code-block:: console
88
89   UART connected to pseudotty: /dev/pts/5
90
91You can manually connect to it like this:
92
93.. code-block:: console
94
95   screen /dev/pts/5
96
97Using offloaded sockets
98***********************
99
100The main advantage over `Using virtual/TAP Ethernet driver`_ is not needing to
101setup a virtual network interface on the host machine. This means that no
102leveraged (root) privileges are needed.
103
104Step 1 - Start app in native_sim board
105======================================
106
107Build and start the ``echo_server`` sample application:
108
109.. zephyr-app-commands::
110   :zephyr-app: samples/net/sockets/echo_server
111   :host-os: unix
112   :board: native_sim
113   :gen-args: -DEXTRA_CONF_FILE=overlay-nsos.conf
114   :goals: run
115   :compact:
116
117Step 2 - run echo-client from net-tools
118=======================================
119
120On the Linux Host, find the Zephyr `net-tools`_ project, which can either be
121found in a Zephyr standard installation under the ``tools/net-tools`` directory
122or installed stand alone from its own git repository:
123
124.. code-block:: console
125
126   git clone https://github.com/zephyrproject-rtos/net-tools
127
128.. note::
129
130   Native Simulator with the offloaded sockets network driver is using the same
131   network interface/namespace as any other (Linux) application that uses BSD
132   sockets API. This means that :zephyr:code-sample:`sockets-echo-server` and
133   ``echo-client`` applications will communicate over localhost/loopback
134   interface (address ``127.0.0.1``).
135
136To run UDP test, type:
137
138.. code-block:: console
139
140   ./echo-client 127.0.0.1
141
142For TCP test, type:
143
144.. code-block:: console
145
146   ./echo-client -t 127.0.0.1
147
148Setting interface name from command line
149****************************************
150
151By default the Ethernet interface name used by native_sim is determined by
152:kconfig:option:`CONFIG_ETH_NATIVE_POSIX_DRV_NAME`, but is also possible
153to set it from the command line using ``--eth-if=<interface_name>``.
154This can be useful if the application has to be
155run in multiple instances and recompiling it for each instance would be
156troublesome.
157
158.. code-block:: console
159
160   ./zephyr.exe --eth-if=zeth2
161
162.. _`net-tools`: https://github.com/zephyrproject-rtos/net-tools
163