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 and IPv4 parameters from command line
149************************************************************
150
151By default the Ethernet interface name used by native_sim is determined by
152:kconfig:option:`CONFIG_ETH_NATIVE_TAP_DRV_NAME`, but is also possible
153to set it from the command line using ``--eth-if=<interface_name>``.
154
155The same applies to the IPv4 address, gateway and netmask. They can be set
156from the command line using ``--ipv4-addr=<ip_address>``,
157``--ipv4-gw=<gateway>`` and ``--ipv4-nm=<netmask>``.
158
159Note that the configuration :kconfig:option:`CONFIG_NET_CONFIG_MY_IPV4_ADDR`
160and the command line arguments work in parallel. This means that if both are
161set, the interface might end up with two IP addresses. In most cases, it does
162make sense to only use one of both at the same time.
163
164This can be useful if the application has to be
165run in multiple instances and recompiling it for each instance would be
166troublesome.
167
168.. code-block:: console
169
170   ./zephyr.exe --eth-if=zeth2 --ipv4-addr=192.0.2.2 --ipv4-gw=192.0.0.1
171   --ipv4-nm=255.255.0.0
172
173.. _`net-tools`: https://github.com/zephyrproject-rtos/net-tools
174